Get started with OAuth 2.0 and Miro
A guide to authenticating a user in Miro with the OAuth 2.0 authorization code flow.
This guide explains how to implement the OAuth 2.0 authorization code flow for Miro. By following these steps, you can obtain an access token and interact with Miro’s REST API on behalf of a user. You will learn how to:
- Prompt users to install your app in Miro.
- Exchange an authorization code for an access token.
- Use the access token in REST API calls.
- Request a new access token with a refresh token.
Goal
Acquire an OAuth 2.0 access token that allows you to make REST API calls to Miro on behalf of a user.
Prerequisites
Before you begin, ensure that you have:
Client ID and client secret
Be sure to note your client ID and client secret. You’ll need both values when exchanging codes for tokens and when requesting refresh tokens.
Step 1: Prompt users to install your app
The OAuth 2.0 authorization code flow begins with prompting a user to install and authorize your app in Miro. This step is where the user grants your app permission to interact with their Miro content.
Tip
For details about the specific permissions you can request, see the Scopes reference.
-
Create an authorization request link. You’ll need the following parameters to build the link:
- Miro authorization base URL:
https://miro.com/oauth/authorize
- response_type:
code
- client_id: Your app’s client ID
- redirect_uri: A redirect URI that you configure in your App Settings
Example request link:
https://miro.com/oauth/authorize ?response_type=code &client_id={YOUR_CLIENT_ID} &redirect_uri={YOUR_REDIRECT_URI}
Make sure that your
redirect_uri
can handle both successful and unsuccessful authorization attempts. - Miro authorization base URL:
-
Direct the user to this link. In your application, you might have a Sign in to Miro or Sync to Miro button. When the user clicks this button, redirect them to the authorization link. The user is then prompted to:
- Sign in with Miro credentials.
- Review the permissions your app is requesting.
- Approve or reject the request.
Note
If you are using the Miro logo in your app or integration, ensure your usage complies with the Miro branding guidelines.
Step 2: Exchange authorization code for an access token
After the user installs and authorizes your application, Miro returns an authorization code. This authorization code cannot be used for API calls directly; you must exchange it for an access token.
Note
Some authentication endpoints have
v1
in the URL; these endpoints are not deprecated.
To exchange the authorization code for an access token, make an HTTP POST request to Miro’s token endpoint. Include:
- client_id (required)
- client_secret (required)
- code (the authorization code you received)
- redirect_uri (must match your app settings)
- grant_type:
authorization_code
Example cURL:
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}'
Example response:
{
"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"
}
You are responsible for storing and securing this token data. A common practice is to store these tokens in a database, linked to your users’ Miro information.
Step 3: Use the access token for REST API requests
With a valid access token, you can make REST API calls on behalf of the user.
- Include the access token in the
Authorization
header. - Use the format
Bearer {ACCESS_TOKEN}
.
Example cURL:
curl --request GET
--url <https://api.miro.com/v2/boards/{BOARD_ID}>
--header 'Authorization: Bearer {ACCESS_TOKEN}'
Step 4: Request a new access token using a refresh token
Miro recommends using expiring access tokens. By default, an access token is valid for 60 minutes and includes a refresh token that remains valid for 60 days. If the access token expires or is compromised, you can use the refresh token to request a new access token.
When you request a new access token using a refresh token, the response includes:
- A new access token
- A new refresh token (resetting the validity period for 60 days)
To request a new token with the refresh token, make an HTTP POST
request to the same Miro token endpoint. This time, set grant_type to refresh_token
and include your current refresh token. You do not need to include the redirect_uri
.
Example cURL:
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}'
Updated about 1 month ago
Learn how to enable REST API authentication from Miro's Web SDK authorization.