Quickstart

Get started and try the REST API in less than 3 minutes.

This tutorial shows you how to get a simple app running in Miro. This app uses our REST APIs.
If you've never built a Miro app before, you're in the right place. Welcome, and let's get started!
By the end of this guide, you'll have a board that has a sticky note with the text Hello, World!.

Prerequisites

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

Step 1: Create a Developer team in Miro

📘

Developer teams for Enterprise plan

If your organization is on an Enterprise plan, go to the Enterprise Developer teams Help Center article to learn how to set up Developer teams for an Enterprise plan.

Step 1: Create a Developer team in Miro describes the procedure for other, non-Enterprise, Miro subscriptions.

The Developer team enables creating and testing apps without affecting production boards; it's comparable to a sandbox, and it has some limitations:

  • A Developer team can have up to 3 boards and up to 5 collaborators.
  • Start testing your app in the Dev team with 3 to 5 users.
  • Once all is well, install the app in a team that supports more than 50 users to check that everything works as expected.

Ensure that you use the Developer team only for development purposes, and not to complete any other type of work or remote collaboration.

  1. Create a Developer team in Miro.

  2. If you previously created the Developer team, the Your apps page appears instead of the Welcome to Miro Developer team box. Skip the steps in this procedure and proceed to Create your app in Miro.

    If you do not have the Developer team, clicking the link in step 1 creates a Developer team for you. Once the
    Developer team is successfully created, the Welcome to Miro Developer team box appears.


    Figure 1. Welcome to Miro Developer team box.

  3. Click Build app, and then proceed to create your app in Miro.

Step 2: Create your app in Miro

  1. On the Your apps page, review the Terms and Conditions, select the I agree to the Terms and Conditions checkbox, and then click Create new app.


    Figure 2. App terms and conditions.

  2. On the Create new app window:

    a. In the App name box, enter Hello world.
    b. Select the Expire user authorization token checkbox to enable the expiring access token and refresh token feature for REST API authorization,

    Using an expiring access token and refresh token enhances your application's security. An access token expires in 1 hour and a refresh token expires in 60 days. When a new access token is requested, you also get a new refresh token. In this scenario, the old access token and refresh token are no longer valid. If you enable this feature, when you exchange an authorization code to an access token, you will also get back a refresh token. For more information, see the REST API authorization flow for expiring tokens.

    🚧

    Enabling or disabling the Expire user authorization feature

    You cannot enable, disable, or update this setting after you create your app.

    c. Click Create app.

    Figure 3. Create new app.

Step 3: Configure your app in Miro

  1. On the app settings page, scroll down to the App URL section.
  2. Under Permissions, select the boards:read and the boards:write checkbox (Figure 4).

    Figure 4. Permissions required for the app.

Step 4: Install the app

  1. At the bottom of the app settings page, click Install app and get OAuth token.

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

    • From the Select a team drop-down menu, select Dev team (Figure 5).

      Figure 5. Select a team.

    • Click Install & authorize. A message notifies you that the app is successfully installed, and you get your access token (Figure 6). You need this access token in the next steps where you call the APIs to create a board and create a sticky note item on the board.

      Figure 6. Access token.

    • Click Close.

Step 5: Create a board

Now that you have an access token, navigate to the Create board reference documentation. To create a board, you need to construct an HTTP request. The documentation includes a sandbox to help you construct these requests by simply filling in the parameter fields.

Screenshot of the Create board documentation pageScreenshot of the Create board documentation page
Figure 7. Screenshot of the Create board documentation page.

To make the create board API call:

  1. Copy the access token you saved earlier into the Authentication field.
  2. Input a name for your new board in the name field. For example, you could use "new board".
  3. Click Try It! to execute the API call.
  4. To see the result of the executed API call, open your Miro dashboard. You should see a new board, with the title you used in your API call.

The Miro REST API reference documentation is intentionally designed to make it easy for you to explore and test each API endpoint. Simply use the access token you created, and you can execute API calls from the documentation, and even view a log of your recent API activity.


Did this page help you?