# 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 [#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.

> The full key and its secret are not stored in plain text and are not shown after creation.

## Creating a key [#creating-a-key]

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

### Key type [#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 [#name]

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

### Environment [#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-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](/en/api/authentication).

### Rate limit [#rate-limit]

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

## Receiving the secret [#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 [#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 [#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.

> If you suspect a key is compromised, revoke it immediately and create a new key with a fresh secret.