There's a new version of Comply One API! We strongly-recommend to start migrating your API Clients as this version will not be supported in the near future. Please review the new version and read the Migration Guides
New Version Migration GuidesComply One API facilitates the exposure of customer’s data to third-party applications in order to allow third-party software/systems to integrate with Stems Accounts on behalf of Stems customers in a secure manner.
By integrating with Comply One API you gain access to a powerful low-level HTTP-based API to query and manage your company's data.
Before you can start interacting with Comply One API, you will need to create an API Client. An API Client is a form of credential that identifies the calling program or application and the user. You can create as many API Clients as need. This information is then used to obtain an access token for Comply One API.
Depending on the type of application using the API Client, you might (or might not) require a Client Secret. To create an API Client, all you need to do is:
There are different types of API Clients you can choose from based on the type of applications you are integrating. Some security implementations are more robust than others. This is covered extensively by the OpenID Connect 1.0 documentations.
Once the API client has been created. You can use it to authenticate with Comply One API
Most of Comply One API's resources implement the Bearer Authentication scheme. This authentication scheme requires clients to send a bearer token in the Authorization header when making requests to protected resources:
Authorization: Bearer <token>
Before you make a request to any of Comply One API resources, you will first need to obtain an access token through Stems Accounts (Refer to Requesting a token Section). While Stems Accounts supports all OpenID Connect 1.0 authentication flows, to access Stems Accounts API you will need to use one of the following OpenID Connect flows to obtain an access token:
In addition to including the Access Token in the Authorization Header, Comply One API also requires a Company Context header to be included in every request. The value of the Company Context header should be set with the ID of the company the current user belongs to:
X-Company-Context: 234
Comply One API uses the Company Context to determine the sub-set of data to return to the user, the sub-set of data to modify and the permissions applied to the operation which is based on the security role the current user has for the specified company
The following sections explain in details how to sign in with Stems Accounts and obtain an Access Token.
Requesting an Access Token is a process that can vary based on the authentication flow you use. Regardless of the authentication flow you use, requesting an Access Token is always done through Stems Accounts. The read more about how to request a token, click the following Authentication Flows:
Because Access Tokens issued by Stems Accounts last for only half an hour, you can use Refresh Tokens to obtain a new access token. However, Refresh Tokens are issued only for API Clients that can securely store sensitive information, authentication flows such as Implicit Flow cannot refresh access tokens because this flow is not allowed to handle Refresh Tokens.
To be able to receive a Refresh Token, API Clients MUST explicitly request the offline_access scope in the token request as explained in the Requesting a token section.
To refresh an access token you will need to issue a POST request to the token endpoint. The request MUST meet the following requirements:
Requirement | Value |
---|---|
Schema | HTTPS |
URL | https://accounts.stems.com.au/auth/connect/token |
HTTP Method | POST |
Accept (request header) | application/json |
Content-Type | application/x-www-form-urlencoded |
The request must also include the following url-encoded form data:
Key/Field | Description |
---|---|
grant_type | Required. The value must be set to refresh_token |
client_id | Required. The ID of your API Client. Refer to the Authentication Section to create an API Client |
client_secret | Required. The pre-configured secret of your API Client |
refresh_token | The Refresh Token obtained from the token request response |
A typical refresh token request would look like the example below:
POST /auth/connect/token HTTP/1.1
Host: accounts.stems
Accept: application/json
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&client_id=your_client_id
&client_secret=your_client_secret
&refresh_token=6d18b6ede4fh504decc2caegttg7b
The response will be the same as when requesting an access token:
{
"id_token": "eyJ0eXAiOiJKV1QiLCJhbhfgdhdgfhdhgGdjl0UGNsTGE2eUYzekFrZnF1RSJ9.eyJpc3MiOiJodHRwOi8v",
"access_token": "0565812445g545gac3a27a5ca8",
"expires_in": 1800,
"token_type": "Bearer",
"refresh_token": "70284617f4a9b9h6j67a7d9ea406"
}
The only difference is that the response will also include an ID Token with information about the claims issued. For more information about ID Tokens please read the OpenID Connect Core Specifications. The response will also include a new Refresh Token which you should use to replace the old one.
All API requests should implement proper error handling in case an error occurs. The API will always return a proper http status code in the response. The following http status code are supported when describing a response error:
Status Code | Description |
---|---|
400 | Bad request |
401 | Unauthorized request |
403 | Forbidden |
404 | Not found |
500 | Internal server error |
Other than the http status codes above, the API should return a 200 response code for a successful request.
In addition to the error status codes described above, the API may also return a JSON object describing the error with more details. The JSON object may have the following properties:
Property | Description |
---|---|
error | A user-friendly error code |
message | Optional. An error message |
error_description | Optional. A string containing more details about the error |
The API Explorer offers a set of tools with documentation of every resources and endpoints exposed by Comply One API. It also allows you to test-drive all endpoints using your own Stems Accounts credentials.
To explore all the available resources and endpoints, click on "API Reference" at the top