# API-ключи

Раздел **API-ключи** предназначен для управления ключами доступа к Tenant API. Каждый ключ определяет тип операций, окружение и набор прав, с которыми ваш бэкенд взаимодействует с API OneKYC.

## Список ключей [#список-ключей]

В таблице отображаются все созданные ключи со следующими атрибутами:

| Атрибут | Описание |
|---------|----------|
| **Тип** | KYC или KYB |
| **Имя** | Пользовательское наименование ключа |
| **Префикс** | Начало ключа для идентификации (например, `kyc_live_...`, `kyc_test_...`, `kyb_live_...`, `kyb_test_...`) |
| **Окружение** | Тестовое или промышленное (production) |
| **Scopes** | Назначенные права доступа |
| **Дата создания** | Дата и время генерации ключа |
| **Последнее использование** | Дата и время последнего запроса с данным ключом |

Отозванные ключи отмечаются соответствующим статусом. Для удобства навигации доступна фильтрация по статусу ключа.

> Полный ключ и секрет не хранятся в открытом виде и не отображаются после создания.

## Создание ключа [#создание-ключа]

Для создания нового ключа нажмите **«Создать ключ»** и заполните следующие параметры:

### Тип ключа [#тип-ключа]

- **KYC** — для верификации физических лиц. Предоставляет доступ к эндпоинтам `/tenant/v1/kyc/`.
- **KYB** — для верификации юридических лиц. Предоставляет доступ исключительно к эндпоинтам `/tenant/v1/kyb/`.

От выбранного типа зависит перечень доступных scopes.

### Имя [#имя]

Произвольное наименование для идентификации ключа (например, «Бэкенд production», «Интеграция CRM», «Тестирование»).

### Окружение [#окружение]

- **Тестовое** — ключ работает с тестовыми данными. Префикс: `kyc_test_` или `kyb_test_`.
- **Production** — ключ работает с реальными данными. Префикс: `kyc_live_` или `kyb_live_`.

Тестовые ключи не имеют доступа к данным промышленного окружения и наоборот.

### Scopes (права доступа) [#scopes-права-доступа]

Права определяют, к каким ресурсам и операциям имеет доступ ключ (например, `applicants:read`, `sessions:create`). Каждый эндпоинт API требует наличия одного или нескольких scopes; при отсутствии необходимого права запрос возвращает ошибку `403 Forbidden`.

Полный перечень scopes приведён в разделе [Аутентификация](/ru/api/authentication).

### Лимит запросов [#лимит-запросов]

При необходимости задаётся ограничение на количество запросов в единицу времени (rate limit).

## Получение секрета [#получение-секрета]

После сохранения параметров система генерирует ключ и **секрет**. Секрет отображается **однократно** — немедленно скопируйте и сохраните его в защищённом хранилище (например, в менеджере секретов вашего бэкенда).

Секрет используется для подписания HMAC-запросов к Tenant API.

## Ротация секрета ключа [#ротация-секрета-ключа]

При подозрении на компрометацию или для плановой ротации можно сгенерировать новый секрет без изменения идентификатора ключа:

1. В списке ключей найдите нужный ключ и нажмите **«Ротация секрета»**.
2. Подтвердите действие — система сгенерирует новый секрет и отобразит его однократно.
3. Скопируйте новый секрет и обновите конфигурацию вашего сервиса.

В отличие от отзыва, при ротации сам ключ (publishable id) остаётся прежним — изменяется только секрет, поэтому достаточно обновить переменную `API_SECRET` на стороне интеграции, не меняя `API_KEY_ID`. Ротация фиксируется в журнале аудита как `api_key.rotated`.

## Отзыв ключа [#отзыв-ключа]

Если ключ скомпрометирован или более не используется:

1. Найдите ключ в списке.
2. Нажмите **«Отозвать»**.
3. Подтвердите действие.

После отзыва все запросы с данным ключом будут отклоняться с кодом `401 Unauthorized`. Операция отзыва является необратимой — для восстановления доступа к API необходимо создать новый ключ.

> При подозрении на компрометацию ключа рекомендуется немедленно выполнить отзыв и создать новый ключ с обновлённым секретом.