Date: 26.06.2017

Using OAuth 2.0

OAuth 2.0 is a protocol that lets your app request authorization to private details in a user's account without getting their password.

You'll need to register your app before getting started. A registered app is assigned a unique Client ID and Client Secret which will be used in the OAuth flow. The Client Secret should not be shared.

The OAuth Flow

Portal uses OAuth 2.0's authorization code grant flow to issue access tokens on behalf of users.



Step 1 - Authorization

Your web or mobile app should redirect users to the following URL:

The following values should be passed as GET parameters:

  • client_id - issued when you created your app (required)
  • scope - permissions to request (required)
  • redirect_uri - URL to redirect back to (required)
  • response_type - specifies response type
  • state - parameter used to avoid forgery attacks by passing in a value that's unique to the user you're authenticating and checking it when auth completes


Step 2 - Token Issuing

If the user authorizes your app, we will redirect back to your specified redirect_uri with a temporary code in a code GET parameter, as well as a state parameter if you provided one in the previous step. If the states don't match, the request may have been created by a third party and you should abort the process.

 If all is well, exchange the authorization code for an access token using the oauth.access  API method.

  • client_id - issued when you created your app (required)
  • client_secret - issued when you created your app (required)
  • code - a temporary authorization code (required)
  • redirect_uri - must match the originally submitted URI (if one was sent)


You'll receive a JSON response containing an access_token (among other details):

   "ok": true,
   "access_token": "xoxp-...-...",
   "expires": 36000,
   "account_id": 123


You can then use this token to call API methods on behalf of the user. The token will continue functioning until the installing user either uninstalls your application and/or token expired.