ДокументацияСправочник APIАутентификация
Аутентификация
Три заголовка авторизации и связанные с аутентификацией ошибки.
Каждый запрос к data plane (/v1/* и /v1beta/*) должен содержать API-ключ. Для совместимости со всеми тремя семействами SDK шлюз проверяет три заголовка по порядку — достаточно любого из них:
| Заголовок | Формат | Типичные клиенты |
|---|---|---|
Authorization | Authorization: Bearer sk-sole-… (принимается и ключ без префикса Bearer) | OpenAI SDK · Codex |
x-api-key | x-api-key: sk-sole-… | Anthropic SDK · Claude Code |
x-goog-api-key | x-goog-api-key: sk-sole-… | Google GenAI SDK |
Передача ключа в параметрах URL (например, ?key= у Google) не поддерживается: строки запроса попадают в журналы доступа и историю браузера, что ведёт к утечкам. Всегда используйте заголовок.
Ошибки аутентификации
| Ситуация | HTTP | Идентификатор |
|---|---|---|
| Ключ не передан | 401 | key_missing |
| Ключ не найден или удалён | 401 | key_invalid |
| Ключ отключён | 403 | key_disabled |
| Срок действия ключа истёк | 403 | key_expired |
| IP не входит в список разрешённых | 403 | key_ip_denied |
| Исчерпан лимит расходов ключа | 402 | key_quota_exhausted |
| Аккаунт заблокирован | 403 | account_disabled |
Формат тела ошибки соответствует SDK, определяемому по пути запроса, а сообщения локализуются под язык аккаунта (до аутентификации — по Accept-Language, по умолчанию английский). См. Ошибки.
Рекомендации по безопасности
- Храните ключи в переменных окружения или менеджере секретов — не в исходном коде и репозиториях конфигурации.
- Не раскрывайте ключи в клиентском коде (например, в браузере); если фронтенду нужен прямой доступ, используйте отдельный ключ с малым лимитом и списком IP.
- Разделяйте ключи по задачам: это изолирует расход и ограничивает инциденты — отключается только затронутый ключ.
- Периодически меняйте ключи, а временным задавайте срок действия и лимит расходов.