ПЛАТФОРМА

Безопасность ключей

Ключ — это доступ к балансу аккаунта. Скоупы, потолки трат и быстрый отзыв ограничивают ущерб, если ключ всё-таки утёк.

Где держать ключ

Только на сервере. Ключ, попавший в браузерный бандл, мобильное приложение или публичный репозиторий, следует считать скомпрометированным — даже если код приватный, сборка уезжает к пользователю. Если API нужен фронтенду, проксируйте запросы через свой бэкенд, чтобы ключ никогда не покидал ваш периметр.

Утёкший ключ отзывается в кабинете за секунды, но потраченные кредиты не возвращаются. Потолок трат — это то, что ограничивает счёт, пока вы не заметили утечку.

Скоупы

Ключ можно ограничить поверхностями chat, images и videos — сервису, который только генерирует картинки, незачем иметь доступ к чату. Запрос к поверхности вне скоупа возвращает 403 permission_error с кодом insufficient_scope. Ключ без выбранных скоупов имеет доступ ко всем поверхностям.

Потолки трат вместо IP-списков

IP-allowlist мы не поддерживаем: он ломается на любой динамической инфраструктуре и создаёт ложное чувство защиты — украденный ключ всё ещё работает с разрешённого хоста. Вместо этого каждому ключу можно задать собственный потолок трат за период и лимит запросов в минуту.

Потолок трат за day · week · month · total. При исчерпании — 402 spend_limit_exceeded.
Свой лимит запросов в минуту, независимый от лимита аккаунта.

Подробности — в разделе Лимиты и кредиты. Практика: отдельный ключ на каждый сервис и окружение, у каждого — свой потолок.

Ротация и отзыв

Полный секрет показывается один раз при создании. Чтобы ротировать ключ, выпустите новый, переключите на него сервис и только затем отзовите старый — так не будет окна отказа. Отзыв применяется немедленно: результат проверки ключа кэшируется на минуту, но отзыв сбрасывает кэш явно.

JSON

{
  "error": {
    "message": "API key lacks scope: images",
    "type": "permission_error",
    "param": null,
    "code": "insufficient_scope"
  }
}

ДалееЛоги и наблюдаемость →