Skip to main content

OAuth Authorization

In some cases, your applications need to read the profile, assets, snapshots, and other data of Messenger users, so you need to use the OAuth 2.0 protocol to authenticate users.

Request to Authorization​

When the bot detects that it is not authorized by a user, it should jump to following url to request authorization from the user:

https://mixin.one/oauth/authorize?client_id=CLIENT_ID&scope=SCOPE&response_type=code&return_to=

In which the parameters are:

Required Parameters

  • client_id - The application's client_id, you can get it from the keystore that previous article has mentioned.
  • scope - Requested permissions, please refer to the this document for more details. It should contain at least the PROFILE:READ permission.
  • response_type - Use code to return authorization code

Optional Parameters

  • state - A random string generated by your application, which you’ll verify later.
  • code_challenge - The code challenge generated by your app, it's a SHA256 hash of your code verifier. For more information about it, please visit here
  • code_challenge_method - The code challenge method, please set it to SHA256
tip

Users may uncheck certain permissions when authorizing. It is recommended that developers only apply for necessary permissions and make proper guidance GUIs in the absence of permissions.

Exchange Authorization Code for Access Token​

After successful authorization, the page will automatically jump to the application's OAuth URL, which will be accompanied by the authorization code and return_to parameters:

YOUR_APP_OAUTH_URL?code=AUTHORIZATION_CODE&return_to=YOUR_APP_RETURN_URL

The developer need to read the AUTHORIZATION_CODE and exchange the access token with it:

POST https://api.mixin.one/oauth/token
Payload
{
    "client_id":    "application's client_id from keystore",
    "code":         "AUTHORIZATION_CODE in the callback URL",
    "client_secret":"the `app secret` that generated in the previous article"
}
Response
{
    "access_token": "user's authorization token",
    "scope":        "list of permissions that the user has given, e.g. 'PROFILE:READ ASSETS:READ'"
}
tip

It is recommended that developers cache the access token and subsequently call the API to access the user data via the access token, to determine whether the user has authorized or not.