> For the complete documentation index, see [llms.txt](https://finext.gitbook.io/one-kyc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://finext.gitbook.io/one-kyc/admin/api-keys.md).

# API keys

The **API keys** section manages access keys for the Tenant API. Each key defines the operation type, environment, and the set of permissions your backend uses when it calls the OneKYC API.

## Key list

The table shows every created key with the following attributes:

| Attribute       | Description                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Type**        | KYC or KYB                                                                                                            |
| **Name**        | A user-defined name for the key                                                                                       |
| **Prefix**      | The start of the key for identification (for example, `kyc_live_...`, `kyc_test_...`, `kyb_live_...`, `kyb_test_...`) |
| **Environment** | Test or production                                                                                                    |
| **Scopes**      | Assigned access permissions                                                                                           |
| **Created at**  | Date and time the key was generated                                                                                   |
| **Last used**   | Date and time of the last request made with this key                                                                  |

Revoked keys are marked with a status badge. The list supports filtering by key status.

{% hint style="info" %}
The full key and its secret are not stored in plain text and are not shown after creation.
{% endhint %}

## Creating a key

To create a new key, click **"Create key"** and fill in the following parameters:

### Key type

* **KYC** — for verifying individuals. Grants access to `/tenant/v1/kyc/` endpoints.
* **KYB** — for verifying businesses. Grants access only to `/tenant/v1/kyb/` endpoints.

The set of available scopes depends on the chosen type.

### Name

A free-form name to identify the key (for example, "Backend production", "CRM integration", "Testing").

### Environment

* **Test** — the key works with test data. Prefix: `kyc_test_` or `kyb_test_`.
* **Production** — the key works with real data. Prefix: `kyc_live_` or `kyb_live_`.

Test keys cannot access production data and vice versa.

### Scopes (access permissions)

Scopes define which resources and operations the key can access (for example, `applicants:read`, `sessions:create`). Every API endpoint requires one or more scopes; if a required scope is missing, the request returns `403 Forbidden`.

The full list of scopes is in [Authentication](/one-kyc/api/authentication.md).

### Rate limit

You can set a request-rate limit for the key when needed.

## Receiving the secret

After you save the parameters, the system generates the key and a **secret**. The secret is shown **once** — copy it immediately and store it in a secure vault (for example, your backend's secrets manager).

The secret is used to sign HMAC requests to the Tenant API.

## Rotating the key secret

When a key is suspected to be compromised, or for scheduled rotation, you can generate a new secret without changing the key identifier:

1. Find the key in the list and click **"Rotate secret"**.
2. Confirm the action — the system generates a new secret and shows it once.
3. Copy the new secret and update your service configuration.

Unlike revocation, rotation keeps the key (publishable id) the same — only the secret changes, so it is enough to update the `API_SECRET` variable on the integration side without touching `API_KEY_ID`. Rotation is recorded in the audit log as `api_key.rotated`.

## Revoking a key

If a key is compromised or no longer used:

1. Find the key in the list.
2. Click **"Revoke"**.
3. Confirm the action.

After revocation, every request made with this key is rejected with `401 Unauthorized`. Revocation is irreversible — to restore API access, create a new key.

{% hint style="warning" %}
If you suspect a key is compromised, revoke it immediately and create a new key with a fresh secret.
{% endhint %}