Skip to Content

User Guide

Business Portal Login

OAuth integration guide

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.

Note that the following guide is for the authorization code grant type. If using OAuth for first-party api access, you may also consider using the client credentials grant type instead.

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

Generating an access token

  1. You will need an OAuth application. 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.
  2. Prepare your authorization request
    Your request will need to include the Client ID, your Redirect URI, and the Scopes you require
  3. After authorization the web browser is redirected to the Redirect URI with an authorization code
  4. 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
  5. 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 user's web browser.

URL:   https://app.nationalcrimecheck.com.au/oauth2/authorize

Request query parameters:

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

Redirect URI response

Responses are returned 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.

URL:  https://app.nationalcrimecheck.com.au/oauth2/token 

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

Security considerations

Your token request MUST occur on a backend server; implicit grant types are not supported. Do not provide the client secret to unsecured environments such as web clients.

Be sure to validate all query parameters received via the Redirect URI.

Your implementation should also make use of the State field to protect against cross-site request forgeries.

More guides in this topic