Управление API-ключами
Найдите свой API-ключ в разделе API & Webhooks в консоли, храните его только на сервере, используйте отдельное sandbox-приложение для тестирования и устраните ошибки 401 и 403.
API & Webhooks, в контексте выбранного приложения. Один ключ на приложение, и ключ и есть окружение - на live-приложении нет отдельного тестового ключа. Это серверный секрет: никогда не размещайте его во фронтенд-коде или в сборке приложения.
Ваш API-ключ находится в разделе API & Webhooks в боковом меню консоли, в контексте того приложения, с которым вы работаете. Обращайтесь с ним как с паролем - он дает полный доступ к API от имени этого приложения.
#Где найти ключ
- Войдите в Business Console
Перейдите на business.didit.me и войдите в систему.
- Выберите приложение
Выберите нужное приложение в выпадающем списке в верхней части консоли. У каждого приложения свой ключ.
- Откройте API & Webhooks
Здесь находится ваш API-ключ, а также адреса ваших webhook-назначений и их signing secrets.
- Create API key создает новый ключ; ключи выдаются на каждое приложение отдельно.
- Секрет показывается здесь только один раз - скопируйте его в свое хранилище секретов.
- Rotate secret заменяет секрет, не меняя имя ключа.
- Last used помогает отличить рабочий ключ от забытого перед тем, как его отзывать.
#API-ключ и signing secret - это разные вещи
Стоит сказать прямо, потому что путаница между ними приводит к непонятным ошибкам:
| Для чего нужен | Где | |
|---|---|---|
| API-ключ | Аутентификация ваших запросов к Didit, в заголовке x-api-key | На приложение |
| Webhook signing secret | Проверка того, что входящий webhook действительно пришел от Didit | На каждое назначение |
Если отправить signing secret вместо API-ключа, вы получите 401. Если проверять webhook с помощью API-ключа, возникнет несовпадение подписи. Обе ошибки встречаются часто.
Ваш API-ключ - это секрет. Никогда не помещайте его во фронтенд-код, публичный репозиторий или сборку мобильного приложения - храните его только на сервере. Ключ в опубликованной сборке приложения - это ключ, который уже есть у злоумышленника. См. аутентификация API.
#Как получить ключ для тестирования
Не тестируйте на продакшене. Создайте отдельное приложение в sandbox-режиме - sandbox-сессии имитируют все внешние проверки, никогда не тарифицируются и не затрагивают реальные данные пользователей. Используйте его ключ во время разработки и держите отдельное live-приложение для реальных верификаций.
На live-приложении нет «тестового ключа». Ключ и есть окружение, поэтому стоит однозначно называть ключи там, где вы храните свои секреты. См. тестирование в sandbox.
#Ротация ключа
Если есть подозрение, что ключ был скомпрометирован, перевыпустите его на той же странице API & Webhooks. Перевыпуск делает старый ключ недействительным немедленно, поэтому сначала обновите его везде, где он используется - иначе ваш продакшен-трафик начнет падать в тот момент, когда вы нажмете кнопку.
Регулярная ротация ключей - хорошая практика. Планируйте ее как деплой, а не как один клик.
#Устранение ошибок 401 и 403
| Ошибка | Причина | Решение |
|---|---|---|
401 | Ключ отсутствует, некорректен или был перевыпущен | Скопируйте текущий ключ из API & Webhooks для этого приложения. Проверьте, нет ли лишних пробелов или кавычек и не вставили ли вы вместо ключа signing secret |
403 | Ключ валиден, но этот вызов не разрешен | Обычно это неверное приложение, поле, доступное только в sandbox, использованное с live-ключом (или наоборот), permission, которого нет у ключа, либо функция, не включенная в вашем аккаунте |
403 на конкретном рабочем процессе почти всегда означает, что ключ принадлежит другому приложению, а не тому, которому принадлежит этот рабочий процесс. Переключите приложение в консоли и скопируйте его ключ. Подробный разбор: ошибки API и что они означают.
#Ограничение возможностей ключа
Если вам нужно ограничить, к каким категориям данных может обращаться ключ - например, чтобы сервис не мог получать изображения документов, - это вопрос permissions, а не настройки ключа, и доступные варианты зависят от вашего аккаунта. Спросите поддержку, а не исходите из предположения, что ключ ничем не ограничен или, наоборот, что он ограничен; оба предположения рискованны в противоположных направлениях.
#Кто в вашей команде видит ключи
Видимость ключей определяется ролью. Роль Developer дает доступ к API-ключам; Reader - нет. Если коллега не может найти эту страницу, сначала проверьте его роль. См. приглашение участников команды и назначение ролей.
#Каждый вызов регистрируется
Запросы с API-ключом отображаются в Audit Logs с привязкой к приложению, а не к конкретному человеку - именно поэтому общий ключ на несколько сервисов усложняет расследование инцидентов. Один ключ на одного потребителя проще анализировать. См. использование журналов аудита.