In this article, we will provide a detailed description of how to obtain access tokens, refresh tokens and ID Tokens via the OAuth 2.0 Authorization Code Flow. Access tokens can be used to access the Class API.
The authorization code flow is designed for use by integrations that can ensure the confidentiality of their client_secret, such as web server applications. The assumption of confidentiality allows this flow to offer additional functionality, most notably supporting the use of refresh tokens.
In order to use this flow, you will require to update your redirect URL by sending an email to partners@class.com.au.
Outline of Flow
The authorization code flow involves the following high-level steps:
- Your integration directs the user to the Class authorization endpoint by making an authorization request. This request identifies your integration and the resources you wish to access.
- Class authenticates the user and prompts them to authorize the requested access.
- Class redirects the user to a redirection endpoint registered for your integration. An authorization code is included in the query component of the redirect URL.
- Your integration makes a token request to the Class token endpoint, including your client credentials and the authorization code.
- Class returns a token response containing the access token and, if requested, a refresh token and/or ID Tokens
Client Authentication
Some requests involved in this flow require client authentication using the client_id and client_secret issued for your integration. This is indicated in the documentation for these requests.
Authentication is accomplished via the HTTP Basic authentication scheme as follows:
- Form the authentication string by concatenating the client_id and client_secret, separated by a single colon, for example: <client_id>:<client_secret>
- Base64 encode the authentication string, for example, PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXTvu78+
- Include the Base64 encoded authentication string in the Authorization request header, preceded by the string "Basic".
The following is an example of a correctly formed Authorization header:
The authorization header is case-sensitive, including the word Basic.
Authorization: Basic PGNsaWVudF9pZD46PGNsaWVudF9zZWNyZXTvu78+
Authorization Request
The authorization request prompts the user for consent before redirecting them to the specified redirect URI. If the authorization was successful, the redirect will also include an authorization code that can be exchanged for an access token.
Requests are made via HTTP GET request to the authorization endpoint. The URI of this endpoint should be obtained dynamically from the authorization_endpoint field of the Discovery document.
The following query parameters are supported for authorization requests:
|
Parameter
|
Required
|
Value |
Description
|
|---|---|---|---|
| response_type | True | code | The desired Response type. For the authorization code flow, the value must be code. |
| client_id | True |
Id issued for your integration |
Identifies the requesting integration to the authorization server. The value must be the id that was issued for your integration. |
| redirect_uri | True | One of the redirection endpoints for your integration |
Specifies where the authorization response will be sent. The value must be an absolute URI and must exactly match one of the redirection endpoints 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 authorization response, in addition to the regular response parameters defined in the Authorization response section. |
| scope | False | A space-delimited list of scope values | List of scope values describing the access being requested by your integration. See Authorization scope for a detailed description of this parameter and the values supported. |
| state | False | Any string | This value is not used by the authorization server, but is echoed in the response to your integration and can be used to track state through the authorization process. |
| response_mode | False | code | Class supports query (default), form_post. |
| prompt | False | none, login, consent |
Specifies how the authorization server should prompt the authorizing user for consent.
With the exception of none, 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 | False | Email address | Provides a hint to the authorization server as to the identity of the authorizing user. This value will be pre-filled in the email field of the login prompt if the user needs to login to Class before authorizing 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:
Authorization response
Once the request has been handled by the authorization 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 authorization code | An authorization 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 authorization request. |
Examples of successful and unsuccessful authorization responses, with white space added for readability:
Token Request
This request requires Client authentication.
The token request is used to exchange the authorization code from the authorization 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. The URI of this endpoint should be obtained dynamically from the token_endpoint field of the Discovery document.
The following parameters are supported for token requests:
|
Parameter
|
Required
|
Value |
Description
|
|---|---|---|---|
| grant_type | True | authorization_code | The type of OAuth 2.0 grant being exchanged. For authorization code grant requests this field must be set to authorization_code. |
| code | True |
The code from the authorization request |
The code that is being exchanged for an access token. Each authorization code can only be exchanged once. |
| redirect_uri | True | The URI from the authorization request |
The value must exactly match URI that was specified in the redirect_uri parameter for the authorization request. |
An example token request, with white space added for readability:
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:
|
Parameter
|
Value
|
Description
|
|---|---|---|
| access_token | An access token | This is the token that is used to access user resources via the Class API. |
| token_type | bearer | The type of access token. Currently, the Class API only supports Bearer tokens and this property will always have the value bearer. |
| refresh_token | A refresh token |
A refresh token that can be used to obtain a new access token without user interaction as described in Refresh request. This property will only be included if offline_access was included in the scope parameter. |
| id_token | An ID Token |
An ID Token containing identity information about the Class user that can be used for authentication. This property will only be included if OpenID was included in the scope parameter. |
| expires_in | String | The number of seconds until the access token expires. |
| scope | A space-delimited list of scope values | The actual scope of the access token. This may be different from what was requested in the scope parameter in the authorization request. See Authorization scope for a detailed description of this parameter and possible scope values. |
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.
Requests are made via an HTTP POST request to the token endpoint. The URI of this endpoint should be obtained dynamically from the token_endpoint field of the Discovery document.
The following parameters are supported for refresh requests:
|
Parameter
|
Required
|
Value |
Description
|
|---|---|---|---|
| grant_type | True | refresh_token | The type of OAuth 2.0 grant being exchanged. For the refresh requests, this field must be set to refresh_token. |
| refresh_token | True |
The refresh token from the original token response |
The refresh token that is being exchanged for an access token. Each refresh token can only be exchanged once. |
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
What's Next?
- Find out more about different Authorization scopes supported by Class.
- List of Class APIs