# Управление API-ключами

Source: https://help.didit.me/ru/account-organization/api-keys
Updated: 2026-10-12

API-ключи создаются в «Разработчикам → API-ключи». Выдайте каждому сервису отдельный ключ с нужным доступом, храните на сервере и проверяйте ошибки 401 и 403.

**Разработчикам → API-ключи**, в контексте выбранного приложения. У каждого
приложения есть ключ **Основной**, и вы можете создавать дополнительные, по
одному на сервис, каждый со своим доступом и сроком действия. Ключ - это
серверный секрет: никогда не размещайте его во фронтенд-коде или в сборке
приложения.

[Video: Настройка API-ключей и проверка вебхуков - Didit Academy](https://www.youtube.com/watch?v=thOMIGbNLP0&t=38)

[Video: Интеграция KYC API за 5 шагов, с ИИ-промптом для настройки в Cursor - Didit Academy](https://www.youtube.com/watch?v=kTAarcImy7E)

Ваши API-ключи находятся в разделе **Разработчикам → API-ключи** в консоли, в контексте того приложения, с которым вы работаете. Обращайтесь с каждым ключом как с паролем: он дает доступ к API от имени этого приложения.

## Где найти ключ

1. **Войдите в Business Console**

   Перейдите на [business.didit.me](https://business.didit.me) и войдите в систему.

2. **Выберите приложение**

   Выберите приложение в карточке приложения в верхней части боковой панели. У каждого приложения свои ключи.

3. **Откройте «Разработчикам», затем «API-ключи»**

   На вкладке **Ключи** перечислены все ключи, начиная с ключа **Основной**, с их доступом, временем последнего использования и сроком действия.

![Страница «API-ключи» в консоли Didit со списком ключей](https://help.didit.me/screenshots/api-keys-light.webp)

*Все ключи этого приложения: сначала ключ Основной, затем созданные вами.*

## Создание ключа

Выдайте каждому сервису, который обращается к Didit, собственный ключ, чтобы видеть, что делает каждый из них, и отзывать его отдельно.

1. **Нажмите «Создать ключ»**

   На странице **Разработчикам → API-ключи**.

2. **Назовите ключ и выберите среду**

   Назовите ключ по сервису, который будет его использовать, выберите **Рабочее** (реальные верификации, платные) или **Песочница** (тестовые данные, никогда не тарифицируются; ключ создается в sandbox-приложении вашей организации) и выберите срок действия: бессрочно, 30 дней, 90 дней, год или до выбранной вами даты.

3. **Выберите доступ**

   **Полный доступ** читает и записывает все - для вашего собственного бэкенда. **Только чтение** видит сессии, решения и медиа, но ничего не может изменить - для партнера, которому нужны только результаты. **Свой набор** позволяет выбрать доступ для каждого ресурса отдельно. Снимите флажок **Включить медиа**, если сервису нужно только решение, а не изображения документов, селфи, видео или PDF-отчеты.

4. **Проверьте и скопируйте секрет**

   Полный секрет показывается один раз, при создании ключа. Сразу скопируйте его в свой менеджер секретов.

Ключ **Основной** - это исходный секрет приложения. У него всегда полный доступ, его можно сменить, но нельзя отозвать.

## API-ключ и signing secret - это разные вещи

Стоит сказать прямо, потому что путаница между ними приводит к непонятным ошибкам:

| | Для чего нужен | Где |
|---|---|---|
| **API-ключ** | Аутентификация ваших запросов к Didit, в заголовке `x-api-key` | На приложение, столько, сколько нужно |
| **Webhook signing secret** | Проверка того, что входящий webhook действительно пришел от Didit | На каждый **эндпоинт** webhook |

Если отправить signing secret вместо API-ключа, вы получите 401. Если проверять webhook с помощью API-ключа, возникнет несовпадение подписи. Обе ошибки встречаются часто.

> **Warning:** Ваш API-ключ - это секрет. Никогда не помещайте его во фронтенд-код, публичный
> репозиторий или сборку мобильного приложения - храните его только на сервере.
> Ключ в опубликованной сборке приложения - это ключ, который уже есть у
> злоумышленника. См.
> [аутентификация API](https://docs.didit.me/getting-started/api-authentication).

## Как получить ключ для тестирования

Не тестируйте на продакшене. Переключите консоль в среду **Песочница** и создайте ключ там или выберите **Песочница** в качестве среды при создании ключа. Sandbox-сессии имитируют все внешние проверки, никогда не тарифицируются и не затрагивают реальные данные пользователей.

Ключ принадлежит одному приложению, а вместе с ним и среде этого приложения: sandbox-ключ никогда не создаст live-верификацию, а live-ключ никогда не создаст sandbox-верификацию. Стоит однозначно называть ключи там, где вы храните свои секреты. См. [тестирование в sandbox](https://help.didit.me/ru/getting-started/sandbox-and-testing).

## Ротация ключа

Если есть подозрение, что ключ был скомпрометирован, откройте его и выберите **Сменить ключ**. Вы получите новый секрет, а старый продолжит работать еще **24 часа**, чтобы вы могли развернуть новый секрет без простоя. После этого каждый запрос со старым секретом будет возвращать 401.

Если ключ должен перестать работать прямо сейчас, выберите вместо этого **Отозвать ключ**. Отзыв останавливает ключ сразу, и его нельзя отменить. Основной ключ можно только сменить.

Регулярная ротация ключей - хорошая практика. Планируйте ее как деплой, а не как один клик.

## Устранение ошибок 401 и 403

| Ошибка | Причина | Решение |
|---|---|---|
| `401` | Ключ отсутствует, некорректен, истек, отозван или был сменен более 24 часов назад | Проверьте ключ в разделе **Разработчикам → API-ключи** для этого приложения. Поищите лишние пробелы или кавычки и проверьте, не вставили ли вы вместо ключа signing secret |
| `403` | Ключ валиден, но этот вызов не разрешен | Обычно это неверное приложение, поле, доступное только в sandbox, использованное с live-ключом (или наоборот), доступ, который ключу не выдали (например, ключ только для чтения пытается что-то записать), либо функция, не включенная в вашем аккаунте |

`403` на конкретном рабочем процессе почти всегда означает, что ключ принадлежит **другому приложению**, а не тому, которому принадлежит этот рабочий процесс. Переключите приложение в консоли и используйте один из его ключей. Подробный разбор: [ошибки API и что они означают](https://help.didit.me/ru/integration/api-errors).

## Ограничение возможностей ключа

Выберите доступ при создании ключа и измените его позже через **Изменить доступ** (секрет остается прежним; доступ Основного ключа изменить нельзя). **Только чтение** не дает партнеру ничего изменить, **Свой набор** задает Нет, Чтение или Запись для каждого ресурса (сессии, решения, медиа, люди, компании и другие), а выключенный флажок **Включить медиа** не дает сервису скачивать изображения документов, селфи, видео и PDF-отчеты. В разделе **Ограничения** ключ также можно ограничить отдельными рабочими процессами, только одобренными сессиями или списком IP-адресов: на запрос не из этого списка приходит ответ 403, а на сессию за пределами рабочих процессов или статусов ключа - ответ 404. Откройте ключ, чтобы точно увидеть, что он может делать; ключ никогда не может сделать больше, чем позволяет его доступ.

## Кто в вашей команде видит ключи

Видимость ключей определяется ролью: чтобы видеть эту страницу, нужно право на чтение API-ключей, которое входит в роль **Разработчик**. Секреты в консоли остаются скрытыми. Если коллега не может найти эту страницу, сначала проверьте его роль. См. [приглашение участников команды и назначение ролей](https://help.didit.me/ru/account-organization/team-members-and-roles).

## Каждый вызов регистрируется

Запросы с API-ключом отображаются в разделе **Журнал аудита** с привязкой к ключу, а не к конкретному человеку. Именно поэтому общий ключ на несколько сервисов усложняет расследование инцидентов: один ключ на одного потребителя проще анализировать. См. [использование журналов аудита](https://help.didit.me/ru/account-organization/audit-logs).