API Reference
Start typing to search…

OAuth flow

Mantle Core API OAuth flow

Mantle uses the OAuth 2.0 Authorization Code Grant Flow to generate access tokens based on requested scopes approved by the user during the grant confirmation page.

The OAuth follows this basic flow:

  • Redirect the user to the authorize url with the desired scopes and parameters needed to identify your application to Mantle
  • Mantle displays a grant confirmation page to the user (who must be logged in to their account). It will show the scopes requested by your application, and ask the user to confirm the grant.
  • Mantle will return a temporary code that your back-end will use, along with your application's unique identifier and secret (important that this is kept on the back-end only), to obtain an access token
  • Your application will persist the access token, along with the scopes requested (useful later), and will use it in the future to make API requests to our core API.

This guide outlines the steps to implement the OAuth 2.0 Access Code Grant Flow using the following URLs:

  • Authorize URL: https://app.heymantle.com/oauth/authorize
  • Token Exchange URL: https://app.heymantle.com/api/oauth/token

Step 1: Redirect User to Authorization URL

Redirect the user to the authorization URL to obtain an authorization code. The URL should include the following query parameters:

  • response_type: Set to code
  • client_id: Your application's client ID
  • redirect_uri: The URL to which the authorization server will send the user after authorization
  • scope: The scope of the access request. See this table for a list of access scopes.
  • state: A unique string to maintain state between the request and callback

Example URL:

https://app.heymantle.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=YOUR_SCOPE&state=YOUR_UNIQUE_STATE

Step 2: Exchange Authorization Code for Access Token

Once you have obtained the authorization code, you need to exchange it for an access token by making a POST request to the token exchange URL. The request should include the following parameters:

  • grant_type: Set to authorization_code
  • code: The authorization code received from the authorization server
  • redirect_uri: The same redirect URI used in the authorization request
  • client_id: Your extension ID
  • client_secret: Your extension secret

Example POST request:

POST https://app.heymantle.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Congratulations

You now have an access token that you can use to make API calls to the Mantle Core API!