OAuth 2.0

The MindMeister API uses OAuth 2.0 for authorization. It allows access to API endpoints on behalf of a user who prior gave consent to the accessing third party application.

Three different authorization flows of OAuth 2.0 are provided to receive a valid access token. Which flow to use depends on the use case and the client application type. The authorization code flow is designed for server-side apps. The implicit flow should be used for client-side apps, e.g. JavaScript apps. The client credentials flow is built for client application access only. No user interaction is permitted.

Before you start with one of the following OAuth 2.0 flows, first you have to register an application as described here.

The OAuth 2.0 endpoints are explained here in detail. For more information about the scopes read this Chapter.

If you just need onetime API access using your own account, you might want to skip the OAuth 2.0 flows and create a personal access token directly.

📘

Use OAuth 2.0 libraries

We strongly encourage you to use OAuth 2.0 libraries. It is best practice to use well-debugged code provided by third-parties. It will provide better security and protect your users.

Authorization Code Flow

The authorization code flow is the safest and most commonly used flow using OAuth 2.0. It is optimized for confidential clients and includes client authentication. Access tokens are not exposed to the end user. Try to use this flow if it fits to your use case.

1) Redirect user to authorization endpoint

The resource owner's user-agent has to be directed to the authorization endpoint https://www.mindmeister.com/oauth2/authorize with the following parameters

• client_id, this is obtained after registration of your application.
• scope, they define the permission level for your app. See scopes for details.
• redirect_uri, is the HTTP endpoint on your server that will receive the response from MindMeister.
• response_type, must be set to code to trigger the authorization code flow.

GET /oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
	&scope=userprofile.email%20mindmeister HTTP/1.1
Host: www.mindmeister.com

If all parameters are present and the request is valid, then the response is a HTTP redirect to either the login or the consent page of MindMeister.

📘

Requiring scopes

Ask always only for the least requiring scopes. The less you're asking for, the more likely the user will grant permission.

2) User authentication and consent

The user has to login on mindmeister.com if he isn't already and then he is asked for granting access to your client application.

3) Receive authorization code after redirect

After the user authorized or denied client access, they are redirected to the redirect URI provided earlier. If the user granted access an authorization code is sent within the query string of the redirect url.

📘

Authorization code validity

The authorization code is only valid for 10 minutes and can't be reused.

4) Exchange code for access token

Your client requests an access token from the MindMeister token endpoint https://www.mindmeister.com/oauth2/token providing the authorization code received in the previous step.

The request must include the following parameters

• grant_type, must be the value authorization_code.
• code, the authorization code received from the MindMeister authorization server.
• client_id, this is obtained after registration of your application.
• client_secret, this is created together with the client_id.
• scopes, they define the permission level for your app. See scopes for details.
• redirect_uri, the same redirect URI that was provided in step 1.

POST /oauth2/token HTTP/1.1
Host: www.mindmeister.com
Content-Type: application/x-www-form-urlencoded

code=CODE&
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET&
redirect_uri=REDIRECT_URI&
grant_type=authorization_code

5) Access token response

The MindMeister authorization server authenticates the client, validates the authorization code and ensures that the given redirection URI matches the URI used to redirect the client in step 3.

If valid, the MindMeister server responds back with an JSON object. This contains the following data:

• access_token, the actual access token. It must be kept secretly, because it allows API access on behalf of the respective user.
• token_type, the type of the access token. In most cases it's Bearer defined in [RFC6750].
• scope, the authorized scopes for this access token.
• expires_in (optional), the lifetime in seconds of the access token. If this parameter is not given then the token doesn't expire by time.

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "scope": "userprofile.email mindmeister",
  "expires_in": 7200
}

🚧

Access token validity

Access tokens without an expires_in parameter don't expire at a certain time and can be revoked only manually from the client or the resource owner.

Implicit Flow

The implicit flow is designed for clients that are publicly exposed and can't keep a client secret, e.g. JavaScript applications running in a browser. In this case the client authentication step is left out and the access token is obtained directly by the client.

This flow relies on the presence of the resource owner and a valid redirect URI. Because the access token is encoded into the fragment of the redirection URI, it may be exposed to the resource owner.

1) Redirect user to authorization endpoint

The resource owner's user-agent has to be directed to the authorization endpoint https://www.mindmeister.com/oauth2/authorize with the following parameters

• client_id, this is obtained after registration of your application.
• scope, they define the permission level for your app. See scopes for details.
• redirect_uri, is the HTTP endpoint of the client application that will receive the access token.
• response_type, must be set to token to trigger the implicit flow.

GET /oauth2/authorize?response_type=token&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
	&scope=userprofile.email%20mindmeister HTTP/1.1
Host: www.mindmeister.com

2) User authentication and consent

The user is asked for granting access to your client application. See authorization code flow for details.

3) Redirect with access token

If the resource owner granted permission in the previous step, then the MindMeister authorization server redirects the user back to the given redirect URI. The access token is provided in the fragment of the redirect URI.

The following parameters are included in the URI fragment

• access_token, the actual access token.
• token_type, the type of the access token. In most cases it's Bearer defined in [RFC6750].
• expires_in (optional), the lifetime in seconds of the access token. If this parameter is not given then the token doesn't expire by time.

HTTP/1.1 302 Found
Location: REDIRECT_URI#access_token=ACCESS_TOKEN&token_type=example&expires_in=7200

4) Obtain access token from fragment

The access token is sent in the fragement of the redirect URI, though it is only exposed to the user-agent and not to the server of the client application. Usually an embedded script within an HTML document is capable of accessing the full redirect URI including the fragment and finally extracts the access token.

Client Credentials Flow

The client application can obtain an access token without user interaction and using only its client credentials as well. This token is not authorized to access any protected user resources, but can be used to request resources under its control.

1) Client authentication with access token request

To obtain an access token the client application requests the MindMeister token endpoint https://www.mindmeister.com/oauth2/token with the following parameters:

• grant_type, must be set to client_credentials.
• client_id, this is obtained after registration of your application.
• client_secret, this is created together with the client_id.
• scopes, they define the permission level for your app. See scopes for details.

POST /oauth2/token HTTP/1.1
Host: www.mindmeister.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET&
scope=userinfo.profilef%20userinfo.email&20mindmeister

2) Access token response

The MindMeister authorization server authenticates the client and if valid, responds with an access token.

The response contains the following data:

• access_token, the actual access token.
• token_type, the type of access token. In most cases it's Bearer defined in [RFC6750].
• expires_in, the lifetime in seconds of the access token.

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "scope": "userprofile.profile userprofile.email mindmeister",
  "expires_in": 7200
}