GuidesWeb SDK 2.0REST API 2.0Live EmbedSCIM APIChangelogRoadmapCommunity
Build your app
These docs are for v1.0. Click to read the latest docs for v2.0.

Overview

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

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

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:

  • Authorization flow for expiring tokens. We recommend using an expiring access token and refresh token as this enhances your application's security. An expiring 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 a refresh token in the response. Read more information on the steps involved in the authorization flow for expiring access tokens.

  • Authorization flow for non-expiring access tokens. The token will continue functioning until the user uninstalls your app from the team. Read more information on the steps involved in the authorization flow for non-expiring access tokens.