Authorization code flow

Hello claims uses OAuth to authenticate users, integrators and to provide granular permissions via integration pathways so third party vendors can connect and interact with our API's. In order to use our API's, you will require a client identifier and a client secret.

The following information assumes that you already have obtained a client identifier and secret, and assumes you are using the staging environment.

Obtaining a user token

In order to utilise our API's, you can direct your users to enable access to their hello claims products.

By directing the user as described below, you will receive a code that you can exchange for an access token allowing you to act on behalf of the user when interacting with our API's. From there, you can make API calls by providing a valid access token with each request.

You will be able to persist access by storing the refresh token provided at the end of this process and continue to exchange the refresh token for new access tokens.

Send a user to authorize your app

Your app should direct users to the following url:

https://uat-login.helloclaims.com.au/login/broker?response_type=code&client_id={cid}&redirect_uri={rduri}&scope={scope}&state={state}

The following values should be passed in as parameters:

Scopes

The scope parameter is a space-separated list of OAuth scopes, indicating what data you’d like your app to be able to access. You should request the minimum scopes required for whatever the user is doing at the time. The complete list of scopes can be found here.

State

The primary reason for using the state parameter is to mitigate CSRF attacks by using a unique and non-guessable value associated with each authentication request about to be initiated. That value allows you to prevent the attack by confirming that the value coming from the response matches the one you sent.

The state parameter is a string so you can encode any other information in it. You send a random value when starting an authentication request and validate the received value when processing the response. If you receive a response with a state that doesn't match, you can infer that you may be the target of an attack because this is either a response for an unsolicited request or someone trying to forge the response.

From a security perspective, neither the request nor the response is integrity-protected so a user can manipulate them. That is true for adding a parameter to the redirect_uri as well.

Redirect URI

When setting up a client application, you will provide a redirect_uri that your users will be redirected to upon successful completion of the OAuth flow. Upon redirection, you will be provided with two query parameters in the request:

Exchange the code

Once the user has completed their login and granted access to your application, they will be redirected to the redirect_uri specified when setting up your client application. You can now exchange the authorisation code for an access token. To do this you will need to make a POST request to our token endpoint:

https://uat-login.helloclaims.com.au/login/token

The request will require an authorization header containing your app’s client_id and client_secret

Authorization: "Basic " + base64encode(client_id + ":" + client_secret)

The request body will need to contain the grant type authorization_code, code and redirect_uri

POST https://uat-login.helloclaims.com.au/login/token
Authorization: "Basic " + base64encode(client_id + ":" + client_secret)
Content-Type: application/x-www-form-urlencoded
 
grant_type=authorization_code
&code=xxxxxx
&redirect_uri=https://myapp.com/redirect

Receive your tokens

The token endpoint will verify all the parameters in the request, ensuring the code hasn’t expired and that the client ID and secret match. If everything checks out, it will generate your tokens and return them in the response.

It will contain the following parameters:

See below for an example response:

{
    "access_token": "xxxxxxxxxxx",
    "token_type": "bearer",
    "expires_in": 1800,
    "refresh_token": "xxxxxxxxxxx",
    ".expires": "2023-05-24T03:19:59.0000000+00:00",
    ".refresh": "True",
    ".issued": "2023-05-24T03:17:59.0000000+00:00"
}

Maintaining authentication

In order to keep your authentication from going stale, and requiring your user to reauthenticate via the OAuth flow, you should regularly exchange the provided refresh_token within the expiry interval. To do this you will need to make a POST request to our token endpoint:

https://uat-login.helloclaims.com.au/login/token

The request will require an authorization header containing your app’s client_id and client_secret

Authorization: "Basic " + base64encode(client_id + ":" + client_secret)

The request body will need to contain the correct grant_type, refresh_token and redirect_uri

POST https://uat-login.helloclaims.com.au/login/token
Authorization: "Basic " + base64encode(client_id + ":" + client_secret)
Content-Type: application/x-www-form-urlencoded
 
grant_type=refresh_token
&refresh_token=xxxxxx
&redirect_uri=https://myapp.com/redirect

Upon successful completion of the refresh_token flow, you will receive back a response with a new access_token and refresh_token. You should replace the existing refresh_token with this new token.

Token expiry

All tokens received have an associated expiry time. Access tokens & refresh tokens can be exchanged prior to expiry.

The above is indicative only and subject to change. Please refer to the expires_in parameter in the response for the actual expiry time.