Skip to Content

User Guide

Business Portal Login

Third-party access

See below for a high-level overview of the steps required to retreive an access token. There are many guides on the internet which detail the finer points of OAuth integration.

Your token request MUST occur on a backend server; implicit grant types (e.g. using client-side scripting) are not supported.


To get started, you will need register an OAuth application. This only needs to be done once within the account of the application developer. Your downstream clients do not need to register applications.

Take note of the Client ID and Client Secret fields. Ensure your client secret is stored in a secure manner and never provide this within client-facing JavaScript or within mobile app source code.

Generate an access token

  1. Prepare your authorization request
    Your request will need to include the Client ID, your Redirect URI, and the Scopes you require
  2. After authorization the web browser is redirected to the Redirect URI with an authorization code
  3. Use the Authorization Code to fetch the Access Token
    This will need to be done server side. It cannot be done client side in the browser.
    Your request will need to include the Client ID, your Client Secret, the Redirect URI originally used, and the Authorization Code you require
  4. You will receive back an Access Token via the JSON response
    This access token can be used with supported APIs

Authorization code request

Authorization code requests use the GET method and should be executed directly within the client's web browser. This can be done easily usign a server-side redirect, by offering a link directly to the authorization page, or by redirecting using JavaScript.

Method: GET


Request query parameters:

  • client_id
  • redirect_uri
  • scope -- see api docs for available values
  • response_type -- must be specified as "code"
  • state

There isn't a response to this request, as it will instead redirect the client's browser to the appropriate page for permissions confirmation.


Redirect URI response

Responses are returned to the specified Redirect URI using a browser redirect and will be a GET request type

Query parameters:

  • code
  • state

Note that authorization codes are single use; once these have been converted into a token then they cannot be reused.


Token request

Token requests should be the POST method and the request fields are provided using form encoding with a JSON response format.

These requests are to be executed server-side within your implementation. They MUST NOT be executed on the client browser.

Method: POST


Request fields include:

  • client_id
  • client_secret
  • redirect_uri
  • grant_type -- must be "authorization_code"
  • code

Response fields:

  • access_token -- the new access token
  • token_type -- always "Bearer"
  • expires_in -- seconds until the access token expires
  • scope -- scopes available for this token
  • refresh_token -- if the offline_access scope was provided