OAuth 2.0 Authorisation Code Flow – Class API

In this article, we will provide a detailed description of why to use this flow, how to obtain access tokens, refresh tokens and id tokens via the OAuth 2.0 Authorisation Code Flow.

Authorisation code flow is the preferred flow and most secure method of accessing the Class API. This flow allows for communication from secure servers only (https) and requires customers to provide authentication that includes MFA, making it very secure and complies with the ATO requirements.

This flow also allows the issue of refresh tokens making it possible for web applications to obtain information without having the end user authenticate again, each time.

To use this flow, you will be required to provide a redirect URL and an image/logo to identify your Application to end users that authorise your Application to obtain data from Class on their behalf. End-users will be able to also revoke permission from your Application if required (cancel refresh tokens).

Note: You can provide us your redirect URL by emailing partners@class.com.au.

Authorisation Code Flow diagram.

Flow Overview

The authorisation code flow is designed for integrations that can keep the client_secret confidential (e.g., web server apps). It supports refresh tokens and involves:

Your integration directs the user to the Class authorisation endpoint by making an authorisation request. This request identifies your Application and the scope of resources you wish to access.

https://apigateway.class.com.au/connect/authorize

Once authorisation is complete, Class redirects the user to the requested redirection endpoint of your Application. An authorization code is included in the response.

https://{yourApp}.{yourDomain}.com.au/class-callback?code={authorisation_code}
Response body includes:
- grant_type:authorization_code
- code:"381553a0-d173-4df9-ac5f-5ed167dxxxxx"

Class authenticates the user and prompts them to authorise the requested access. The user will need to provide their Class credentials including their MFA. This step is handled by the Class App during the first step above.
Your Application makes a token request to the Class token endpoint and includes the authorisation_code obtained above.

https://apigateway.class.com.au/connect/token

Class returns a token response containing the access token and, if requested, an id_token and/or refresh token. It also returns the scope granted.

Response body includes:        
"token_type":"bearer",
"access_token":"gIcXxxp90FodZ8wFhdiEimminDE4Y1dTbW2AfhS859-xxxxxx",
"id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ij-xxxxxx",
"refresh_token":"a2a86079-4885-44ec-9233-ac629a4xxxxx",
"expires_in":"899",
"BusinessName":"{Customer_Business_Name}",
"BusinessCode":"{Customer_Business_Code}",
"scope":"class_profile openid offline_access target:b/{Customer_Business_Code}"

Your application calls the Class API endpoint and exchange Access token for data

Authorisation Header

Requests involved in this flow require basic authentication using the client_id and client_secret issued for your Application/integraiton. The authorisation header is case-sensitive, including the word Basic. It can be constructed as follows:

Concatenate the client_id and client_secret, separated by a single colon for example: <client_id>:<client_secret>`
Base64 encode the authentication string above, for example: PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXTvu78+
Include the Base64 encoded authentication string in the Authorisation request header, preceded by the string "Basic".

Example header (placeholder value):

# Authorisation header example
Authorization: Basic PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXTvu78+

The authorisation request prompts the user for consent, then redirects them to the specified redirect_uri. If successful, the redirect includes an authorization code.

Requests are made via HTTP GET to the authorisation endpoint. The endpoint URI should be obtained dynamically from the authorization_endpoint field of the Discovery document.

Authorisation Query Parameters:

The following query parameters are supported for authorisation requests:

Parameter	Required	Value	Description
`response_type`	True	`code`	Must be `code` for this flow.
`client_id`	True	Your issued client ID	Identifies your integration.
`redirect_uri`	True	One of your registered redirect URIs	Must exactly match a registered redirect URI (including protocol, case, and any trailing character). A query string may be included and will be echoed back.
`scope`	False	Space-delimited list	Describes requested access. See Authorisation scope docs.
`state`	True	Any string	Echoed back to mitigate CSRF. Class mandates using a random, unlinked value. See RFC6749 §10.12.
`response_mode`	False	`query` (default) or `form_post`	Select how the authorisation response is returned.
`prompt`	False	`none`, `login`, `consent`	Controls login/consent prompting. Multiple values may be space-delimited (except `none`).
`login_hint`	False	Email address	Pre-fills the login email field.

Example authorization request (wrapped for readability):

GET https://apigateway.class.com.au/connect/authorize?
response_type=code& 
client_id={Your ClientId for your Application}& 
scope=class_profile openid offline_access fund.read&
redirect_uri=https://.application.yourdomain.com.au/class_oauth_callback&
state=security_token%Y2eeg2eCMB5owJ&
prompt=consent

Authorisation Response

Once the request has been handled by the authorisation server, the user will be redirected to the URI specified in the redirect_uri parameter in the request.

For unsuccessful requests, the response consists of a single parameter, error, with an error value as described in Error codes.

For successful requests, the response parameters are as follows:

Parameter	Value	Description
`code`	An authorisation code	An authorisation code that can be exchanged for an access token. As described in the following section.
`state`	Any string	The same value that was specified for the state parameter in the authorisation request.

Token Request

The token request is used to exchange the authorisation code from the authorisation response for an access token that can be used to access the Class API.

Requests are made via an HTTP POST request to the token endpoint. https://apigateway.class.com.au/connect/token

The following parameters are supported for token requests:

Parameters:

Parameter	Required	Value	Description
`grant_type`	True	`authorization_code`	Must be `authorization_code`.
`code`	True	Authorization code	Single-use code from the authorization response.
`redirect_uri`	True	Same as before	Must exactly match the `redirect_uri` used in Step 3.

Example token request:

Request Headers

POST https://apigateway.class.com.au/connect/token
Authorization: Basic PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXTvu78+
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: app.class.com.au
Content-Length: 123

Request Body

grant_type=authorization_code&
code=1fd827c4-9ea3-4290-a99a-84c7d62d8b11&
redirect_uri=https%3a%2f%2fapp.class.com.au%2foauth-callback

Token Response

The token endpoint returns a response in JSON format.

For unsuccessful requests, the JSON object will contain two properties, error with an error value as described in Error codes, and error_description containing a more specific, human-readable error message.

For successful requests, the JSON object will contain the following properties:

Success example:

# HTTP/1.1 200 OK
# Content-Type: application/json;charset=UTF-8
# Cache-Control: no-cache
# Pragma: no-cache

{
  "access_token": "CBfgN5Z5...",
  "token_type": "bearer",
  "expires_in": "899",
  "scope": "target:b/OAUTH_TEST offline_access business.fund.create fund.read",
  "refresh_token": "9e0fccdb-ec4f-4e6a-ae60-83ad66be9547",
  "BusinessName": "OAuth Test Business",
  "BusinessCode": "OAUTH_TEST"
}

Error example:

# HTTP/1.1 400 Bad Request
# Content-Type: application/json;charset=UTF-8
# Cache-Control: no-cache
# Pragma: no-cache

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Refresh Token Request

If offline_access was included in scope, you can exchange the refresh_token for a new access_token without user interaction. Each refresh token is typically single-use.