Manually create an app in Your apps

create-miro-app is the quickest way to create a sample app to use as scaffolding to further customize.
As an alternative, you can create a new app and configure the main app settings through the app settings UI under Your apps.

Prerequisites

Before you begin, ensure that you have the following prerequisites:

• You have a Developer team.
• Your development environment includes Node.js 14.15 or a later version.
• To run your app locally, your web browser must allow the HTTP transport protocol.
  Recommended web browser: Google Chrome
  Apple Safari doesn't allow HTTP; therefore, it doesn't allow the sample app to run locally.

Step 1: create your app in Miro

1. Sign in to Miro, and then click your user account avatar.

2. From the drop-down menu, select Settings.

3. In the app settings view, click the Your apps tab.

4. In the Your apps view, click + Create new app.
   
   Figure 1. To start creating a new app from your app settings, click + Create new app.

5. On the Create new app modal:

   1. In the App name input field, enter the name of your app.
      For example: Hello world.
   2. Click Create app.
      
      Figure 2. On the Create new app modal, give the app a name and assign it to a team.

Step 2: configure your app in Miro

You can configure your app in one of the following ways:

• Edit the plain text app manifest in the online editor.
• Select the appropriate options in the app settings UI.

This step described how to configure your app using the app manifest editor.

1. On the app settings page, click Edit in Manifest.
   
   Figure 3. Click Edit in Manifest to open the app manifest editor.

2. In the app manifest editor, set at least the following properties:
   
   Figure 4. Configure your app by editing the app manifest.

   • appName: the name of the app that you entered in the App name input field, on the Create new app modal.

   • sdkVersion: the field is pre-populated with the SDK_V2 value.
     The app is configured to use the Miro Web SDK version 2.0.
     After setting the target Web SDK version to 2.0, it's not possible to change this property.

   • sdkUri: enter 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: 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.
     For example, to enable your app to read from and write to the board, specify the following permissions:

     • board:read
     • board:write

   • icons:

     • colored: enter the <svg .../> contents of your app's monochrome icon.
     • outline: enter the <svg .../> contents of your app's full-color icon.

3. Once done, save your settings by clicking Save.

4. To go back to the app settings UI and proceed with the app installation, in the top-right corner of the page click Edit in UI.

Step 3: install your app

In the app settings UI, do the following:

1. Under Permissions, click Install app and get OAuth token.

2. On the Install app to get OAuth token dialog:

   1. In the Select a team list, select Dev team.
      
      Figure 5. Install app to get OAuth token dialog.
   2. Click Install & authorize.
      A message notifies you that the app is installed.
      If you're using only the Miro Web SDK ignore the access token information.
      
      Figure 6. Installation confirmation and tokens.
   3. Click Close.

See also

• App manifest reference
• Build your first Hello, World app
• create-miro-app on npm