An API credential is how a system authenticates with the ComplyAdvantage Mesh API. It consists of an access key and a secret, which your integration exchanges for a 24-hour token. You create it once, in the account the integration will use.

In new Mesh accounts, users have access to the web application only, so integrations authenticate with an API credential. This article explains how to create a credential and use it for the first time.

Before you start

• Your role. The Admin system role can create API credentials, as can a custom role that has the API credential permissions enabled in the Roles and permissions page. See Creating and managing custom roles.

• The account. A credential belongs to the account in which it is created, and its tokens act on that account only.

• The permissions. Ask the integration team which endpoints they will call. Each endpoint's reference page names the permissions it requires, and they cannot be changed after the credential is created. See System roles and permissions.

• The integrations. We recommend one credential per integration, created in the account that integration uses, with only the permissions it requires.

Creating a credential

The secret is displayed only once, so decide where you will store it before you start.

1. Log in to Mesh and confirm that you are in the account the integration will use.

2. Select Settings from the main navigation.

3. Under Access Management, select API credentials.

4. Select Create API credential.

5. Enter a name that identifies the integration.

6. Select the permissions the integration requires. You can only assign permissions that your own role holds.

7. Set an expiry date if the credential should stop working on a given date. Leave it empty for no expiry.

8. Select Create. Mesh displays the access key and the secret.

9. Copy the secret, then the access key, and store both securely before you leave the page.

Sharing the credential

The person who creates the credential is usually not the person who uses it. We recommend sharing the access key, the secret, and the name of the account through a secrets manager, and never in a ticket, an email, or a chat message.

Managing credentials

A credential cannot be edited. To change it, create a new credential and deactivate the previous one. A credential belongs to the account, not to its creator, and remains valid after that user is deactivated. Managing users explains how a user is deactivated.

Deactivating a credential

Deactivate a credential when its integration is retired, when its secret has been exposed, or when a new credential has replaced it. Deactivation is permanent and takes effect immediately: the credential can no longer issue tokens, and the tokens it has already issued are invalidated.

1. Under Settings and Access Management, select API credentials.

2. Select the credential.

3. Deactivate it and confirm. The credential remains in the list, marked as deactivated.

Using the credential

The token endpoint is documented in full in Create an API access token in the Mesh API reference. Your integration sends the access key and secret to POST /v3/token as JSON:

POST https://api.mesh.complyadvantage.com/v3/token
Content-Type: application/json

{
    "access_key": "<your access key>",
    "secret": "<your secret>"
}

The response contains the token and its validity in seconds:

{
    "access_token": "eyJhbGciOi...",
    "expires_in": 86400,
    "scope": "read:api write:api",
    "token_type": "Bearer"
}

Send the token with every request as Authorization: Bearer {access_token}. A token is valid for 24 hours and cannot be refreshed. Request a new token when the integration starts, shortly before the 24 hours elapse, or when a request returns 401.

To confirm which account the credential acts on, call GET /v2/accounts/me with the token. The response identifies the account.

What a failed response means