Skip to main content

App manifest

Each Miro app must include an app manifest file. The app manifest is a YAML file with essential metadata information about the app.

For example, it defines the app name, the Web SDK version it uses, the resources it can access, the actions it can perform, as well as OAuth details such as the redirect URI used in the OAuth code grant flow.

This reference describes the properties in the current app manifest.

appName

  • string
  • required

Defines the name of the app.
When the app is published, the app name may be displayed on the Miro UI, the Miro Marketplace, as well as in app management flows, based on the app configuration.

sdkVersion

  • string
  • required

Selects the Web SDK version that the app should use.

📘

  • After selecting the Web SDK 2.0, it's not possible to undo the action.
  • The Miro Web SDK 1.0 is deprecated, and it's flagged for retirement in the near future.

sdkUri

  • string

The URL of the server hosting your app.
Required only for apps that use the Web SDK.
To enable rendering the app on a board, specify the URL pointing to your app on the server that hosts it.
The protocol must be HTTPS.

📘

Public vs private app URL

  • If you're developing locally, you can use localhost and HTTP.
    Example: http://localhost:3000/
  • If you set a URL that is part of a LAN or a VPN, the app is available to all users who can access the LAN or VPN.
    In this case:
    • The app isn't publicly available through the internet.
    • It's not possible to register Miro webhooks with a non public URL.
  • If you set a URL that is publicly accessible on the internet, the app is available to any users who can access the URL.
    In this case:
    • The app is publicly available through the internet.
    • It is possible to register Miro webhooks with a public URL.

scopes

  • list of strings
  • required

The Miro REST API and the Web SDK implement user access control through scopes. Scopes define the permissions your app requires to interact with a board and to work as designed.
When users install your app, they are prompted to provide consent for the required scopes.

Allowed scopes:

  • boards:read
  • boards:write
  • identity:read
  • identity:write
  • team:read
  • team:write
  • microphone:listen
  • webcam:record
  • screen:record
  • auditlogs:read (Enterprise plan only)
  • organizations:read (Enterprise plan only)
  • organizations:teams:read (Enterprise plan only)
  • organizations:teams:write (Enterprise plan only)

boardPicker.allowedDomains

  • list of strings
  • required

BoardsPicker enables users to select a board to embed, and to set its access settings.
BoardsPicker only runs on domains that are on the allowedDomains list. If you're developing locally, use localhost as a domain.
The allowedDomains list must contain only the domain where BoardsPicker is allowed to run. It cannot contain the transport protocol (http://, https://).

redirectUris

  • list of strings

Required only for apps that use the REST API.
If you want to authorize your app users with OAuth2.0, you need to connect your server with the Miro REST API.
Provide a redirect URI pointing to the page that you intend to load after a successful user authorization.

redirectUriForSdk

  • string

Redirect URI used during Web SDK authorization.
If you specify a redirect URI here, the Web SDK authorization process also starts the OAuth 2.0 code grant flow for the REST API.

icons.outline

  • string

The <svg .../> contents of your app's monochrome icon.
The shape of the icon image must be square.
Monochrome icons cannot include more than 1 color.
The monochrome outline icon is visible on the app toolbar, after installing the app.
To split the icon into multiple lines in the YAML file, you can use block scalars (>-).

icons.colored

  • string

The <svg .../> contents of your app's full-color icon.
The shape of the icon image must be square.
If you publish your app, the full-color icon is visible on the app toolbar panel and on the Miro Marketplace.
To split the icon into multiple lines in the YAML file, you can use block scalars (>-).

Example app manifest file

appName: My application
sdkVersion: SDK_V2
sdkUri: https://my.webapp.com/sdk.html
boardPicker:
  allowedDomains: 
    - my.webapp.com
    - localhost
redirectUris:
  - http://localhost:3000/auth/redirect
  - https://my.webapp.com/auth/redirect
redirectUriForSdk: https://my.webapp.com/auth/redirect
scopes:
  - boards:read
  - boards:write
icons:
  colored: >-
    <svg viewBox="0 0 24 24" height="48" width="48"
    xmlns="http://www.w3.org/2000/svg" class="outline-icon--app"
    fill="currentColor"><path d="M18.071 10.172 20.9 7.343a1 1 0 0 1 1.415
    1.414l-2.829 2.829 2.122 2.121-4.243 4.243a6 6 0 0 1-8.485
    0l-.707-.707-4.243 4.242a1 1 0 1 1-1.414-1.414l4.242-4.243-.707-.707a6 6 0 0
    1 0-8.485l4.243-4.243 2.121 2.122 2.829-2.829a1 1 0 1 1 1.414 1.415l-2.829
    2.828 4.243 4.243zm-7.778-4.95L7.464 8.05a4 4 0 0 0 0 5.657l2.829 2.829a4 4
    0 0 0 5.657 0l2.828-2.829-8.485-8.485z"/></svg>
  outline: >-
    <svg viewBox="0 0 24 24" height="48" width="48"
    xmlns="http://www.w3.org/2000/svg" class="outline-icon--app"
    fill="currentColor"><path d="M18.071 10.172 20.9 7.343a1 1 0 0 1 1.415
    1.414l-2.829 2.829 2.122 2.121-4.243 4.243a6 6 0 0 1-8.485
    0l-.707-.707-4.243 4.242a1 1 0 1 1-1.414-1.414l4.242-4.243-.707-.707a6 6 0 0
    1 0-8.485l4.243-4.243 2.121 2.122 2.829-2.829a1 1 0 1 1 1.414 1.415l-2.829
    2.828 4.243 4.243zm-7.778-4.95L7.464 8.05a4 4 0 0 0 0 5.657l2.829 2.829a4 4
    0 0 0 5.657 0l2.828-2.829-8.485-8.485z"/></svg>