Introduction

All applications need authorization to access content on Miro boards. Authorization is an explicit consent that a user grants to an app, which then allows access to specific Miro user data or team data. The data that is shared is managed through scopes, which define the permissions your app requires to work as designed and to interact with a Miro board. In the authorization flow, the user reviews the scopes your app is requesting before deciding whether to authorize your application.

The Miro platform offers two means of authorization, depending on how your app interacts with Miro user data. Applications that solely use the Miro Web SDK can use the Web-plugin Authorization approach to prompt a user for authorization to act on behalf of that user in the Miro board. Applications that use the Miro REST APIs need to implement the OAuth 2.0 authorization code flow.

All applications interacting with the Miro REST API must implement the OAuth 2.0 authorization code flow. OAuth 2.0 allows users to share specific data with an application while keeping their other information private. For example, with the proper flow and scopes, an application can use OAuth 2.0 to obtain permission to create and manage the sticky notes on a user’s Miro board, without needing access to the user’s password or other Miro boards.

Here’s a summary of the steps involved in the OAuth authorization code flow:

Prerequisites

• Create a Developer team in Miro
• Create your app in Miro
• Configure your app in Miro
• Install your app in Miro

OAuth authorization code flow

1. Create authorization request link
2. Request user for authorization
3. Exchange authorization code with access token
4. Use access token for REST API requests
5. (Only for expiring access tokens) Get new access token using refresh token

• (Optional) Get access token context
• (Optional) Revoke token

The OAuth 2.0 Authorization Code flow first prompts a user into an authorization flow via the authorization request link. Upon completion, the user is redirected to the application via the redirect URL defined by your app. If the authorization flow was successful, your application can retrieve the authorization code from that URL, and then exchange that authorization code for an access token. If the authorization flow was unsuccessful, the server returns an error.

All API requests require an access token. The access token contains information about which scopes the user has authorized, and which API calls your application is permitted to make on the user’s behalf. You can use either an expiring access token or a non-expiring access token. You can select to use an expiring or a non-expiring token while creating your app. You cannot enable, disable, or update this setting after you create your app. When creating your app, you can choose between the following:

Use an expiring access token

We recommend using an expiring access token combined with a refresh token to enhance your application's security.

• Access token lifespan: The access token expires after one hour.
• Refresh token lifespan: The refresh token expires after sixty days.

When you request a new access token, a new refresh token is also issued. The previous access token and refresh token become invalid.

If you enable this feature, the response to exchanging an authorization code for an access token will also include a refresh token. For detailed instructions, see authorization flow for expiring tokens.

Use a non-expiring access token

A non-expiring access token remains valid until the user uninstalls your app from their team.

For detailed instructions, see authorization flow for non-expiring access tokens.