---
title: "Identity Hub"
description: "Identity Hub is CM.com's all-in-one solution for online identity verifications. It lets you verify and identify end-users through a single hosted flow that combines multiple identification methods, such as iDIN, ID Scan and Yivi. This documentation focuses on the API integration."
canonical: "https://docs.cm.com/verification/identity-hub"
---

# Identity Hub

> Identity Hub is CM.com's all-in-one solution for online identity verifications. It lets you verify and identify end-users through a single hosted flow that combines multiple identification methods, such as iDIN, ID Scan and Yivi. This documentation focuses on the API integration.

Source: https://docs.cm.com/verification/identity-hub

Identity Hub is CM.com's all-in-one solution for online identity verifications. It lets you verify and identify end-users through a single hosted flow that combines multiple identification methods, such as [iDIN](https://docs.cm.com/verification/idin/), [ID Scan](https://docs.cm.com/verification/id-scan/) and Yivi. This documentation focuses on the API integration.

The identification methods available to the end-user depend on the account's contract. Contact your account manager to find out which methods are enabled for your account.

For complete technical documentation with specifications for all field types, JSON objects, and methods, you can consult our complete [API reference](https://docs.cm.com/verification/identity-hub/v1/api-reference).

If you need technical assistance, please contact your account manager or [support](https://www.cm.com/app/support).

## Usage

The steps for using the service are:

1. [Create a transaction](https://docs.cm.com/verification/identity-hub/identify-a-user#create-a-transaction) with the desired `returnUrl` and `requestedFields`, and an optional `locale`.
2. Redirect the end-user to the hosted `url` returned in the response.
3. The end-user selects an identification method and completes the flow on the hosted page or on their mobile device.
4. After the flow completes, the end-user is redirected back to the `returnUrl` with the `transactionId` and `state` appended as query parameters.
5. [Retrieve the transaction](https://docs.cm.com/verification/identity-hub/identify-a-user#get-a-transaction) using the transaction id to obtain the final state, the method used, and any collected data.

Alternatively, provide a `callbackUrl` when creating the transaction to be notified of state changes instead of relying on the redirect. See [Events](https://docs.cm.com/verification/identity-hub/events).

Match the hosted page to your brand with custom colors and a font. See [Branding](https://docs.cm.com/verification/identity-hub/branding).

## Authentication

Before you can start using the API, you need API credentials. Credentials consist of a key ID and a secret. Contact your account manager to get production credentials. Credentials should be kept secret.

To authenticate you need to use your credentials to generate a JWT Bearer token. The [JWT token](https://jwt.io/introduction/) has to be generated using the `HS256` algorithm and your credentials. This JWT has to contain the following attributes: `iat`, `nbf`, and `exp` in the payload, as well as the attribute `kid` in the header of the JWT. This `kid` attribute needs to contain the Key ID of your credentials.

The generated token needs to be passed via the HTTP Authorization header:

```text title="Request headers"
Authorization: Bearer GENERATED_TOKEN_HERE
```

There are many libraries available for different programming languages that can help you to generate a JWT. See the Libraries tab on [https://jwt.io](https://jwt.io).

**Example**

Assuming we want to create a token that is valid for 60 seconds and we have received the following credentials:

- **Key ID**: `3b438437-04a4-40bb-8389-54bb02766fba`
- **Secret**: `AC4Etykn7jusGR5FwLDAtILtQbiQbTMKedP31szXg4WlSbjGEXyNMZ`

We need to create a JWT with the following properties:

```json title="JWT header"
{
    "alg": "HS256",
    "typ": "JWT",
    "kid": "3b438437-04a4-40bb-8389-54bb02766fba"
}
```

```json title="JWT payload"
{
    "iat": 1704067200,
    "nbf": 1704067200,
    "exp": 1704067260
}
```

- `iat`: the time when the token was generated.
- `nbf`: the time after which the token is valid, usually equal to `iat`.
- `exp`: the time when the token will expire.

:::note
Make sure these are UNIX timestamps in seconds
:::

This results in the following token:

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjNiNDM4NDM3LTA0YTQtNDBiYi04Mzg5LTU0YmIwMjc2NmZiYSJ9.eyJpYXQiOjE3MDQwNjcyMDAsIm5iZiI6MTcwNDA2NzIwMCwiZXhwIjoxNzA0MDY3MjYwfQ.lTzOd4cKOan2rwL4fHjwOffc0dp3pwYjDdl4uM1WluU
```

Add this token to the `Authorization` header in the API request.

```text title="Request headers"
Authorization: Bearer GENERATED_TOKEN_HERE
```

> The [https://jwt.io](https://jwt.io) website provides a way to inspect or validate JWT tokens.

## Sandbox

Use the sandbox to build and test your integration end to end before you go live: run the complete verification flow, test your webhook handling, and check how your application deals with different results. The sandbox uses test credentials for the identification methods, so no real identity data is verified and no real personal data is needed. ID Scan also accepts specimen documents, so you can test the full flow without a real identity document. Because results are simulated, a successful sandbox result is not a real verification and must never be used for real onboarding decisions.

Sandbox and production use different credentials. Request your sandbox credentials via the [identity-hub registration form](https://www.cm.com/app/verification-registration/identity-hub). When your integration is ready, switch to production by replacing the base URL and credentials with your production ones, and run a first real verification to confirm everything works.

## Environments

| Environment | Base URL | Use for |
| - | - | - |
| Sandbox | `https://api.cm.com/identity-hub-sandbox/v1/` | Building and testing your integration |
| Production | `https://api.cm.com/identity-hub/v1/` | Verifying real people |
