oAuth Tokens #

All access to the Claiming.com.au API is secured with oAuth tokens. With your oAuth credentials, you need a token for all communications with the API.

Important Notes:

• Tokens are valid for 24 hours, so your code should include a process for dealing with expired tokens
• We recommend storing the token expiry time so you know when to proactively request another

Credentials and tokens are specifically for 1 server:

• If you make all API calls from a centralized or cloud server, one set of credentials is sufficient (vendor-level credentials)
• If your solution is installed on end-user hardware, each installation will need its own credentials and token management

POST - Create an oAuth Token #

With your vendor client_id and client_secret, you can request a token. If all your calls are from a centralized or cloud server, this token is all you need for further API calls.

Note: Token expiry is given in UTC time.

Endpoint:

{{base_url}}/{{version}}/oauth/token

Headers:

Request Body:

{
    "client_id": "{{client_id}}",
    "client_secret": "{{client_secret}}",
    "grant_type": "client_credentials"
}

Example Request:

curl --location 'https://sandbox.claiming.com.au/v2/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "{{ClientId}}",
    "client_secret": "{{ClientSecret}}",
    "grant_type": "client_credentials"
}'

Example Response:

Body:

{
    "access_token": "xxxxxxxxxxxxxxxxxxxxxxx",
    "expiry": "2021-06-09 04:49:28"
}

Headers:

POST - Create oAuth Credentials for a Location #

For installed software, you will use your vendor-level credentials to generate client_id and client_secret for each installed site. These location-level credentials can then be used to generate tokens for that site.

Note: Location-level credentials do not need the “?location=?” query string parameter in other requests.

Endpoint:

{{base_url}}/{{version}}/locations/{{location_id}}/oauth

Headers:

Example Request:

curl --location --request POST 'https://sandbox.claiming.com.au/v2/locations/25/oauth' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data ''

Example Response:

Body:

{
    "ClientId": "XXXXXXXXXXXXXXXXXXXX",
    "ClientSecret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

DELETE - Revoke oAuth Credentials for a Location #

You can revoke credentials for an installed site with this call, using your vendor-level token.

Endpoint:

{{base_url}}/{{version}}/locations/{{location_id}}/oauth

Headers:

Example Request:

curl --location --request DELETE 'https://sandbox.claiming.com.au/v2/locations/25/oauth' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data ''

Example Response:

Body:

{
    "Success": true,
    "Message": "OAuth credentials and existing tokens have been revoked."
}