When performing your initial request you can supply the offline_access scope and then the response will include an additional refresh_token field.

These refresh tokens have a much longer expiry than standard access tokens (typically around a month). They cannot be used for API requests and can only be used to generate new access tokens. Generating access tokens in this manner does not require interactive user access.

Method: POST

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

Request fields:

• client_id
• client_secret
• grant_type -- must be "refresh_token"
• refresh_token

Response fields:

• access_token -- the newly generated access token, these are valid for typically one hour
• token_type -- always "Bearer"
• expires_in -- seconds until the access token expires, e.g. 3600 seconds
• scope -- scopes available for this token
• refresh_token -- if this is supplied, then the refresh token has been updated and future requests should use this new refresh token. If not supplied, then the existing refresh token is still valid and shoud continue to be used.

Refresh token expiry

Refresh tokens have a much longer expiry than access tokens, typically around a month; in contrast standard access tokens are only valid for several hours.

Making requests for new access tokens (using the refresh token endpoint as described above) will also cause the refresh token expiry to be updated. This is the only way to extend the lifetime of the refresh token.

When requesting a new access token, if the refresh_token field is returned then your stored refresh token should be updated to the new token. If this field is not returned then the existing refresh token is still valid and should continue to be used.

If the refresh token has expired, then the oauth handshake will need to be performed again.

Usage workflow

A typical workflow would be that prior to any api request, your integration code would request a new access token by performing a token refresh.

As part of this token refresh process your integration should cache the access token (in the access_token field) for the period specified by expires_in field, minus a few seconds to allow for network jitter.

When performing the refresh, take care that if the refresh_token field is returned then this new refresh token should be stored; if not returned then subsequent refreshes should continue to use the old refresh token.

If your integration is not going to access the API very often, then your integration should also perform an additional refresh at least once per month, such as on a scheduled task. This would ensure that the refresh token remains valid.