Skip to main content

Get started with OAuth 2.0 and Miro

Applications that use the Miro REST API need to implement the OAuth 2.0 authorization code flow. This guide will show you how to prompt the user to install your app in Miro, how to exchange an authorization code for an access token, and how to use a refresh token to request a new access token.

Goal

Implement the OAuth 2.0 authorization code flow and acquire an access token that can be used to make calls to the Miro REST API.

Prerequisites

Before you begin, make sure that you:

Prompt users to install your app in Miro

The OAuth 2.0 authorization code flow begins when your application prompts a user to install and authorize your app in Miro. This is when a user grants your application permission to interact with their Miro content.

Note: for more information on specific permissions you can request, see Scopes.

Step 1

To prompt a user for this authorization, you’ll first need to create an authorization request link. This link requires the Miro authorization base URL, a response_type, a client_id, and a redirect_uri.
Let’s take a look:

https://miro.com/oauth/authorize
    ?response_type=code
    &client_id={your_client_id}
    &redirect_uri={your_redirect_uri}

The authorization base URL is the Miro API endpoint for beginning an authorization flow. Set the response_type to code to receive standard HTTP response status codes. The client_id is the value you noted in the prerequisites, and serves as an identifier for your application. The redirect_uri is the URI of the page that you want to load after the user has completed authorization, which you will need to configure in your App Settings.

Note: if you are using an OAuth library for your integration, check the library documentation for guidance on what the redirect URI should be. Otherwise, make sure your URI will be able to handle the logic of both a successful and an unsuccessful user authorization.

Step 2

Now that you have your authorization request link, you’ll need to direct the user to that link. For example, if your application includes a “Sign in to Miro” or a “Sync to Miro” button, the user should be directed to this link upon clicking that button. This will prompt the user to sign in with their Miro credentials, review the permissions your application is requesting, and then approve or reject that request.
Keep in mind that if you are using the Miro logo, you’ll want to review the Miro branding guidelines.

Exchange authorization code for access token

Once a user installs and authorizes your application, you’ll receive a response that includes an OAuth 2.0 authorization code. This authorization code cannot be used to make calls to the Miro REST API. You’ll need to first exchange the authorization code for an access token.

Step 3

📘

Note

Authentication endpoints are not being deprecated. These endpoints remain the same and use v1 in the endpoint URLs, as documented.

To exchange an authorization code for an access token, you’ll need to make a call to the Miro token API endpoint. This is done by first constructing an HTTP request with your client ID, client secret, and redirect URI. These values confirm the identity of your application so that Miro can confidently issue an access token.

curl --request POST \
    --url 'https://api.miro.com/v1/oauth/token
        ?grant_type=authorization_code
        &client_id={CLIENT_ID}
        &client_secret={CLIENT_SECRET}
        &code={AUTHORIZATION_CODE}
        &redirect_uri={REDIRECT_URI}'

The response will include the access token and refresh token, the scopes that were granted for that token, an expiration time, the Miro user_id of the authorizing user, and a team_id for the Miro team the application was installed on. 

{
    "user_id": "9876543210123456789",
    "refresh_token": "eyJtaXJvLm9yaWdpbiI6ImV1MDEifQ_-PIBKmE9rzQuL3bUeAvUEGFEhLk",
    "access_token": "eyJtaXJvLm9yaWdpbiI6ImV1MDEifQ_o-P91OccaII0A63CDSK--x21xiI",
    "expires_in": 3599,
    "team_id": "1234567890987654321",
    "scope": "boards:write boards:read",
    "token_type": "bearer"
}

Keep in mind that you are responsible for storing and securing this data. A common solution is to maintain a database that links your application's user information with their Miro user information, and store the tokens there.

Use access token for REST API requests

Step 4

Now that you have an access token, you can make API calls on behalf of that user. To do so, simply include the access token in an Authorization header when constructing your HTTP request.

For example:

curl --request GET \
    --url https://api.miro.com/v2/boards/{BOARD_ID} \
    --header 'Authorization: Bearer {ACCESS_TOKEN}'

Get new access token using refresh token

When using the OAuth 2.0 authorization code flow, it is recommended that you use expiring access tokens. A non-expiring token will continue to be valid until revoked. An expiring token is valid for 60 minutes, but comes with a refresh token that is valid for 60 days. This means that even if the access token becomes compromised, it will not be valid for long.

When requesting an access token using a refresh token, the response will include a new access token and a new refresh token, resetting the clock on both tokens.

Step 5

To request an access token using a refresh token, you’ll follow the same process as explained in Step 3, but now using a refresh token instead of an authorization code. You will not need to include the redirect URI this time.

curl --request POST \
    --url 'https://api.miro.com/v1/oauth/token
        ?grant_type=refresh_token
        &client_id={CLIENT_ID}
        &client_secret={CLIENT_SECRET}
        &refresh_token={REFRESH_TOKEN}'