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.
Access tokens are only valid for a short time, currently set to 12 hours although this timeframe is not guaranteed and may change in the future. The current token lifetime is provided in the response.
If you need another access token then you should re-authenticate each time as the permissions step is skipped if permissions have already been granted, or you may choose to make use of refresh tokens and the offline access scope.
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.
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
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
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
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