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 Authorization 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). 

Outline of Flow

The authorization code flow involves the following high-level steps:

1. 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://app.class.com.au/connect/authorize

   Once authorization 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"
           

2. 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.  
3. Your Application makes a token request to the Class token endpoint and includes the authorisation_code obtained above.
   

   https://app.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. 
   

   https://app.class.com.au/connect/token
   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}"
   
   

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

Authorisation Request

The authorisation request prompts the Class Application user for consent before redirecting them to the requested redirect URI. The consent requested will be determined by the scope(s) included in the request.
If the authorisation is successful, the response will also include an authorization code that can be exchanged for an access_token.

If the authorisation scope includes "openid" & "class_profile" then you will be able to also obtain an id_token when exchanging the authorisation code.

If the authorisation scope includes "offline_access" then you will be able to also obtain a refresh_token when exchanging the authorisation code.

 

Authorisation Header

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

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

Authorization: Basic PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXTvu78+

Authorization Query Parameters

The following query parameters are supported for authorization requests:

Parameter	Value	Description
response_type (required)	code	For the authorisation code flow, the value must be code.
client_id (required)	Your Application client_id issued by Class	Identifies the requesting integration to the authorisation server. The value must be the client_id that was issued for your Application/integration.
redirect_uri (required)	Your Applications redirect endpoint	Specifies where the authorization response will be sent. The value must be an absolute URI and must exactly match the redirection endpoint registered for your Application, including protocol (https), case, and trailing "/" character if present. Optionally, a query string may be included in the URI. If present, any query parameters will be echoed in the authorisation response, in addition to the regular response parameters defined in the Authorisation response section.
scope (required)	A space-delimited list of scope values	List of scope values describing the access being requested by your Application/integration. See Authorization scope for a detailed description of this parameter and the values supported.
state	Any string	This value is not used by the authorisation server, but is echoed in the response to your integration and can be used to track state through the authorisation process.
prompt	none, login, consent	Specifies how the authorisation server should prompt the authorising user for consent. none Never display a login or consent prompt to the user. This request will fail unless the user is already logged in to Class and has already authorised the requested access previously. login Requires the user to re-login to Class before authorising the request, even if they are already logged in to Class. consent Always prompt the user for consent, even when access to the request scopes has already been granted previously. Multiple values may be specified for this parameter in a space-delimited list. For example,prompt=login consent combines both the login and consent behaviours.
login_hint	Email address	Provides a hint to the authorisation server as to the identity of the authorising user. This value will be pre-filled in the email field of the login prompt if the user needs to login to Class before authorising the request.

While the state parameter is optional as per OAuth specification, Class mandates that this parameter be used to mitigate the risk of cross-site request forgery (CSRF) attacks. State parameter should be a random value and not linked to any account and is not traceable for subsequent requests. Please see Section 10.12 of the OAuth 2.0 specification for further details. 

An example authorization request, with white space added for readability:

GET https://app.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:

Token Request

This request requires Client authentication.

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://app.class.com.au/connect/token

The following parameters are supported for token requests:

An example token request, with white space added for readability: 

POST https://app.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

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:

Examples of successful and unsuccessful token responses, with white space added for readability:

Example successful response

HTTP/1.1 200 OK
 Content-Type: application/json;charset=UTF-8
 Content-Length: 959
 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"
 }

Example error response

HTTP/1.1 400 Bad Request
 Content-Type: application/json;charset=UTF-8
 Content-Length: 77
 Cache-Control: no-cache
 Pragma: no-cache
 
 {
 "error":"invalid_client",
 "error_description":"Client authentication failed"
 }

This request requires Client authentication.

The refresh request allows integrations with offline_access to obtain new access tokens without interaction from the user via an authorization request. A refresh token is a credential that OAuth uses to get a new access token without user interaction. This allows the Authorization Server to shorten the access token lifetime for security purposes without involving the user when the access token expires.

Requests are made via an HTTP POST request to the token endpoint. 

The following parameters are supported for refresh requests:

An example refresh request, with white space added for readability:

POST https://app.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: 75
 
 grant_type=refresh_token&
 refresh_token=9e0fccdb-ec4f-4e6a-ae60-83ad66be9547