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 KnowaKYC 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.
The full key and its secret are not stored in plain text and are not shown after creation.
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_orkyb_test_. - Production — the key works with real data. Prefix:
kyc_live_orkyb_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.
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:
- Find the key in the list and click "Rotate secret".
- Confirm the action — the system generates a new secret and shows it once.
- 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:
- Find the key in the list.
- Click "Revoke".
- 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.