API-ключи создаются в «Разработчикам → API-ключи». Выдайте каждому сервису отдельный ключ с нужным доступом, храните на сервере и проверяйте ошибки 401 и 403.
Разработчикам → API-ключи, в контексте выбранного приложения. У каждого приложения есть ключ Основной, и вы можете создавать дополнительные, по одному на сервис, каждый со своим доступом и сроком действия. Ключ - это серверный секрет: никогда не размещайте его во фронтенд-коде или в сборке приложения.
Ваши API-ключи находятся в разделе Разработчикам → API-ключи в консоли, в контексте того приложения, с которым вы работаете. Обращайтесь с каждым ключом как с паролем: он дает доступ к API от имени этого приложения.
#Где найти ключ
- Войдите в Business Console
Перейдите на business.didit.me и войдите в систему.
- Выберите приложение
Выберите приложение в карточке приложения в верхней части боковой панели. У каждого приложения свои ключи.
- Откройте «Разработчикам», затем «API-ключи»
На вкладке Ключи перечислены все ключи, начиная с ключа Основной, с их доступом, временем последнего использования и сроком действия.
#Создание ключа
Выдайте каждому сервису, который обращается к Didit, собственный ключ, чтобы видеть, что делает каждый из них, и отзывать его отдельно.
- Нажмите «Создать ключ»
На странице Разработчикам → API-ключи.
- Назовите ключ и выберите среду
Назовите ключ по сервису, который будет его использовать, выберите Рабочее (реальные верификации, платные) или Песочница (тестовые данные, никогда не тарифицируются; ключ создается в sandbox-приложении вашей организации) и выберите срок действия: бессрочно, 30 дней, 90 дней, год или до выбранной вами даты.
- Выберите доступ
Полный доступ читает и записывает все - для вашего собственного бэкенда. Только чтение видит сессии, решения и медиа, но ничего не может изменить - для партнера, которому нужны только результаты. Свой набор позволяет выбрать доступ для каждого ресурса отдельно. Снимите флажок Включить медиа, если сервису нужно только решение, а не изображения документов, селфи, видео или PDF-отчеты.
- Проверьте и скопируйте секрет
Полный секрет показывается один раз, при создании ключа. Сразу скопируйте его в свой менеджер секретов.
Ключ Основной - это исходный секрет приложения. У него всегда полный доступ, его можно сменить, но нельзя отозвать.
#API-ключ и signing secret - это разные вещи
Стоит сказать прямо, потому что путаница между ними приводит к непонятным ошибкам:
| Для чего нужен | Где | |
|---|---|---|
| API-ключ | Аутентификация ваших запросов к Didit, в заголовке x-api-key | На приложение, столько, сколько нужно |
| Webhook signing secret | Проверка того, что входящий webhook действительно пришел от Didit | На каждый эндпоинт webhook |
Если отправить signing secret вместо API-ключа, вы получите 401. Если проверять webhook с помощью API-ключа, возникнет несовпадение подписи. Обе ошибки встречаются часто.
Ваш API-ключ - это секрет. Никогда не помещайте его во фронтенд-код, публичный репозиторий или сборку мобильного приложения - храните его только на сервере. Ключ в опубликованной сборке приложения - это ключ, который уже есть у злоумышленника. См. аутентификация API.
#Как получить ключ для тестирования
Не тестируйте на продакшене. Переключите консоль в среду Песочница и создайте ключ там или выберите Песочница в качестве среды при создании ключа. Sandbox-сессии имитируют все внешние проверки, никогда не тарифицируются и не затрагивают реальные данные пользователей.
Ключ принадлежит одному приложению, а вместе с ним и среде этого приложения: sandbox-ключ никогда не создаст live-верификацию, а live-ключ никогда не создаст sandbox-верификацию. Стоит однозначно называть ключи там, где вы храните свои секреты. См. тестирование в sandbox.
#Ротация ключа
Если есть подозрение, что ключ был скомпрометирован, откройте его и выберите Сменить ключ. Вы получите новый секрет, а старый продолжит работать еще 24 часа, чтобы вы могли развернуть новый секрет без простоя. После этого каждый запрос со старым секретом будет возвращать 401.
Если ключ должен перестать работать прямо сейчас, выберите вместо этого Отозвать ключ. Отзыв останавливает ключ сразу, и его нельзя отменить. Основной ключ можно только сменить.
Регулярная ротация ключей - хорошая практика. Планируйте ее как деплой, а не как один клик.
#Устранение ошибок 401 и 403
| Ошибка | Причина | Решение |
|---|---|---|
401 | Ключ отсутствует, некорректен, истек, отозван или был сменен более 24 часов назад | Проверьте ключ в разделе Разработчикам → API-ключи для этого приложения. Поищите лишние пробелы или кавычки и проверьте, не вставили ли вы вместо ключа signing secret |
403 | Ключ валиден, но этот вызов не разрешен | Обычно это неверное приложение, поле, доступное только в sandbox, использованное с live-ключом (или наоборот), доступ, который ключу не выдали (например, ключ только для чтения пытается что-то записать), либо функция, не включенная в вашем аккаунте |
403 на конкретном рабочем процессе почти всегда означает, что ключ принадлежит другому приложению, а не тому, которому принадлежит этот рабочий процесс. Переключите приложение в консоли и используйте один из его ключей. Подробный разбор: ошибки API и что они означают.
#Ограничение возможностей ключа
Выберите доступ при создании ключа и измените его позже через Изменить доступ (секрет остается прежним; доступ Основного ключа изменить нельзя). Только чтение не дает партнеру ничего изменить, Свой набор задает Нет, Чтение или Запись для каждого ресурса (сессии, решения, медиа, люди, компании и другие), а выключенный флажок Включить медиа не дает сервису скачивать изображения документов, селфи, видео и PDF-отчеты. В разделе Ограничения ключ также можно ограничить отдельными рабочими процессами, только одобренными сессиями или списком IP-адресов: на запрос не из этого списка приходит ответ 403, а на сессию за пределами рабочих процессов или статусов ключа - ответ 404. Откройте ключ, чтобы точно увидеть, что он может делать; ключ никогда не может сделать больше, чем позволяет его доступ.
#Кто в вашей команде видит ключи
Видимость ключей определяется ролью: чтобы видеть эту страницу, нужно право на чтение API-ключей, которое входит в роль Разработчик. Секреты в консоли остаются скрытыми. Если коллега не может найти эту страницу, сначала проверьте его роль. См. приглашение участников команды и назначение ролей.
#Каждый вызов регистрируется
Запросы с API-ключом отображаются в разделе Журнал аудита с привязкой к ключу, а не к конкретному человеку. Именно поэтому общий ключ на несколько сервисов усложняет расследование инцидентов: один ключ на одного потребителя проще анализировать. См. использование журналов аудита.
Не нашли ответ? Поговорите с человеком.
Укажите ID организации и ID сессии, о которой спрашиваете.