oAuth #

All access to the Claiming.com.au API is secured with oAuth. With your oAuth credentials, you need a token for all communications with the API. Please note that tokens are valid for 24 hours, so your code should include a process for dealing with expired tokens. We recommend to store the token expiry time from the Creat Token request so you know when to proactively request another.

Credentials and tokens are specifically for 1 server. If you make all API calls from a centralised or cloud server then one set of credentials is sufficient. We call these vendor-level credentials. If your solution is installed on end user hardware then each location will need its own credentials and token management. The process for each is slightly different.

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 vendor-level token. If all your calls are from a centralised 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 (vendor-level token required) #

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=nnn” query string parameter used in other requests, these credentials are only valid for the one location.

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 location (vendor-level token required) #

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."
}