Authentication

WoAG Occupation Coding Service User Guide

Authentication information and instructions.

Cite
Released
30/06/2025
Release date and time
30/06/2025 11:30am AEST

An authentication token is required to use the Coding Service. This is a unique, time-limited access key which is used to authenticate all API calls to the service.

Note: Authentication is only required once every hour. 

Do not include an authentication script in every API call. Too many token requests may result in an error. This error may also occur for you if there have been excessive authentication requests from anyone else in the organisation. See Session Token Usage for more information.

Get an authentication token

To get an authentication token, you must first call the service’s authentication endpoint with an authorisation header. More details are available in the AWS documentation, but the key input parameters are described below.

Request syntax

POST /oauth2/token HTTP/1.1
Host: string 
Content-Type: application/x-www-form-urlencoded
Authorization: string
{
    grant_type: "client_credentials"
}

See Integration script examples for an example PowerShell script to request an authentication token. 

Request header parameters

Host: 
     The host name for your chosen API. This will be either https://partner-coder.auth.abs.gov.au or
     https://public-coder.auth.abs.gov.au depending on whether you have registered for the partner or the 
     public coding service.

Authorization: 
     Basic authorisation method with a base64 authorisation token (encodedAuthString), computed from the 
     client ID and client secret provided upon registration. 
     encodedAuthString can be computed via the bash command:

     $ echo -n "${clientID}:${clientSecret}" | base64
     Type: String

Response syntax

HTTP/1.1 200 OK
Content-Type: application/json
{
     access_token: "string"
}

Response elements

access_token
     Your unique access token which can be used to authenticate all API calls to the coding service.
     Type: String

Examples

On registering for the coding service, this user was issued with the following:

  • ClientID: “client1”
  • ClientSecret: “secret123”

encodedAuthString should be the base64 encoding of “client1:secret123” and the entire request is as follows:

Sample request
POST /oauth2/token HTTP/1.1
Host: https://partner-coder.auth.abs.gov.au
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50MTpzZWNyZXQxMjM=
{
    grant_type: "client_credentials"
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json
{
    access_token: "example token"
}

(See Integration script examples for an example PowerShell script to request an authentication token.)

Use an authentication token

To authenticate against the coding API service, you will need to include your access token in the header of any API calls.

  • Your token will last one hour from the time of issue, after which you will need to request a new token.
  • You do not need to request a new token for each API call.


The API calls are of a short duration, usually less than a few seconds. When initiated, each call will check the authentication and then continue with the rest of the call. If the call was approved at the start, it will return a response if the timer runs out. 

Asynchronous batch calls may take longer to return results, and you may have to re-authorise to receive the results.

Request header parameters

Authorization
     The authorisation token retrieved via the Authentication mechanism.
     Type: String

Host
     The host name for your chosen API. This will be either https://partner-coder.api.abs.gov.au or 
     https://public-coder.api.abs.gov.au depending on whether you have registered for the partner or the
     public coding service.
     Type: String

Session token usage

For optimal performance, please reuse a single session token per hour, and avoid hitting service limits by caching tokens. Single session tokens will be valid for all users interacting with webforms or interfaces during that time. 

  • Token Type: AWS Cognito M2M session token.
  • Token Validity: 60 minutes.
  • Usage Scope: Expect shared use of a single token across all users of a webform/integration/process.
  • Storage: Store locally in your backend (e.g., in-memory, file, cache).
  • Rate Guidance: Max 1 token request per hour per webform.

Exceeding this limit may result in your service being blocked or degraded. Restrictions are time limited, and requests for authorisation during this time will result in HTTP 403 errors.

Please ensure that any scripts written for others to copy and paste (i.e. for coding single records or running small batches) do not include a token call. Provide authentication scripts separately to be used at need. 

Recommended integration pattern

  1. Backend checks for existing token.
  2. If token is valid, reuse it.
  3. If token is expired or missing, request a new one.
  4. Use the token to call the API for all users of the form.

Token re-use flow diagram

Recommended flow for session token re-use across users of a webform.

User accesses webform - backend checks for existing token. If no token exists or token has expire, new token is requested and stored in backend. If token is valid, use token to call API.