API-ключи и безопасность
API-ключи и безопасность
Где создать ключ?
В Dashboard → API Keys. Скопируйте ключ при создании: повторно он не отображается.
Сколько ключей нужно?
По одному на каждый компонент, который вызывает BeatAPI: приложение, инструмент или окружение.
Это бесплатно и сразу упрощает управление. Поле by_api_key в GET /v1/usage показывает расходы без дополнительного учёта, а скомпрометированный или проблемный ключ можно отозвать, не останавливая остальные компоненты.
Разработка, тестовое окружение и рабочая среда не должны использовать один ключ.
Куда ключ не должен попадать?
Туда, где его может прочитать пользователь или посторонний:
- JavaScript браузера и любые клиентские сборки. Всё отправленное в браузер следует считать открытым.
- Мобильные приложения: их декомпиляция не представляет большой сложности.
- Публичный репозиторий или закрытый репозиторий, который впоследствии могут открыть.
- Логи, отчёты об ошибках, скриншоты и обращения в поддержку.
- Параметры URL: они попадают в журналы прокси, историю браузера и серверные логи.
Передавайте ключ в заголовке: Authorization: Bearer <key>.
Как не допустить попадания ключа в репозиторий?
Используйте переменную окружения и исключите файл с её значением из системы контроля версий:
Такой способ ввода также не оставляет ключ в истории команд. Добавьте .env, ~/.codex/auth.json и конфигурационные файлы инструментов с ключами в .gitignore.
Если интеграция поддерживает переменную окружения, предпочитайте её вставке ключа в файл. В Codex CLI для этого предусмотрен env_key.
Что делать при утечке ключа?
Сначала отзовите его в Dashboard → API Keys, затем создайте новый и обновите использовавшие его компоненты. Отзыв действует немедленно.
Порядок важен. Если сначала создать новый ключ, а старый отозвать позже, некоторое время утёкший ключ всё ещё сможет расходовать баланс.
Затем проверьте by_api_key в GET /v1/usage на незнакомые вызовы.
Как часто менять ключи?
По расписанию, которого вы сможете придерживаться, и немедленно, если сотрудник с доступом ушёл или возникло подозрение на утечку. Отдельный ключ для каждого компонента упрощает замену: обновлять нужно только одно развёртывание.
Может ли браузер напрямую вызывать BeatAPI?
Не с постоянным API-ключом. Для Realtime API сервер создаёт сессию и передаёт браузеру краткоживущий client_secret, ограниченный этой сессией. См. Realtime API. Остальные методы вызываются только с сервера.
Исключение — чтение сгенерированных медиа. URL результата задачи содержит собственные подписанные данные доступа в параметрах запроса и разрешает чтение только этого объекта. Поэтому браузер может загрузить его через <img> или <video> без заголовка авторизации.
Используются ли мои данные для обучения?
BeatAPI не обучается на ваших запросах. Перед отправкой лиц, голосов и других персональных данных либо обработкой материалов от имени другого человека прочитайте политику конфиденциальности и условия использования.
Как убедиться, что вебхук отправлен BeatAPI?
Проверяйте подпись по исходным байтам запроса до разбора JSON. Повторная сериализация меняет тело, и подпись перестаёт совпадать. Проверяйте также время, чтобы защититься от повторной отправки старого события. См. вебхуки.
Непроверенный обработчик вебхука позволяет постороннему записывать данные в вашу систему. Неуспешную проверку подписи рассматривайте как возможную атаку, а не просто ошибку.
Что попадает в журналы?
Запросы записываются с request_id для поддержки и учёта расходов. Сообщая о проблеме, передавайте этот ID, но никогда не сам ключ.