1. Overview

Comply 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.

2. Getting Started

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:

1. Login to Stems Accounts
2. Once logged in, click on My Profile under your user name at the left of the top menu
3. Once you are on your profile, click on API Clients
4. Then click on Create New to create a new API Client

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

2.1 Migration Guide

If you have an existing API Client integrated with earlier versions of this API and you want to migrate to this version, we recommend you to read the following documentation

3. Authentication

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:

1. Implicit Flow
2. Authorization Code
3. Proof Key for Code Exchange
4. Resource Owner Password Credentials

Company Context

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

Users with multiple companies

Note that the Company Context header can only contain the ID of one company. If a user belongs to more than one companies, you should only set the ID of only one company

The following sections explain in details how to sign in with Stems Accounts and obtain an Access Token.

4. Requesting a 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:

1. Implicit Flow
2. Authorization Code
3. Proof Key for Code Exchange
4. Resource Owner Password Credentials

5. Refreshing a token

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:

The request must also include the following url-encoded form data:

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.

6. Handling Errors

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:

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:

7. API Explorer

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