API-ключи

Что такое API-ключ

API-ключ (API key) — длинная случайная строка, которую сервис выдаёт при регистрации приложения. Клиент прикладывает её к каждому запросу, а сервер по ключу понимает, кто пришёл: какие права у этого клиента, сколько запросов ему положено и кому выставить счёт.

Ключ — это одновременно логин и пароль в одной строке. Отдельного имени пользователя нет: кто предъявил ключ, тот и владелец. Отсюда все правила обращения с ним — как с паролем, а не как с идентификатором.

sk_live_51H8xY2eZvKq3mN7pR4tW9dF1
└──┬──┘└─┬┘└──────────┬──────────┘
 тип   среда   случайная часть

Многие сервисы делают префикс осмысленным: по нему видно тип и среду (test или live), а автоматические сканеры находят утёкшие ключи в публичных репозиториях именно по такому префиксу.

Как передают ключ

# Заголовок Authorization — самый распространённый вариант
curl https://api.example.com/v1/orders \
  -H "Authorization: Bearer $API_KEY"

# Отдельный заголовок — тоже нормально
curl https://api.example.com/v1/orders \
  -H "X-API-Key: $API_KEY"

# Query-параметр — так делать не надо
curl "https://api.example.com/v1/orders?api_key=$API_KEY"

Третий вариант встречается в старых API, но он плох: query-строка оседает в логах Nginx, в истории браузера, в заголовке Referer и в системах мониторинга. Ключ, попавший в логи, считайте скомпрометированным. Передавать ключ можно только по HTTPS: в открытом HTTP он летит по сети текстом.

Ключ, JWT и OAuth

Практическое правило: API-ключ — для машин, токен — для людей. Ключ в браузерном JavaScript — это ключ, опубликованный в интернете: код фронтенда открыт любому. Если фронтенду нужен внешний API, запрос проксируют через свой бэкенд, а ключ остаётся на сервере.

Как хранить и не потерять

• Переменные окружения, не код. Ключ читают из окружения или файла .env, который добавлен в .gitignore. Захардкоженный ключ уезжает в репозиторий навсегда — удаление в новом коммите не помогает, история остаётся.
• Секреты в CI. В CI/CD ключи кладут в secrets, а не в текст пайплайна. Значение маскируется в логах сборки.
• Хранилище секретов. Для команды и нескольких окружений — HashiCorp Vault или встроенный secrets-механизм Kubernetes: доступ по ролям и журнал обращений.
• Минимум прав. Если сервис умеет ограничивать ключ областью (только чтение) и списком IP — используйте это. Ключ читалки, попавший наружу, не спишет деньги.
• Ротация. Отдельный ключ на каждое приложение и окружение и плановая замена. Хороший API позволяет держать два активных ключа одновременно — чтобы менять без простоя.
• Отзыв. Утёк — отзывайте немедленно, а не после разбирательства. Проверьте историю вызовов: чужие запросы обычно видны по всплеску активности.

# Ключ живёт в окружении, а не в исходниках
export OPENAI_API_KEY="sk-..."
python app.py

import os

api_key = os.environ["API_KEY"]   # падаем сразу, если ключа нет

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

Связанные термины

• API — то, к чему открывает доступ ключ
• JWT и токены — альтернатива для пользовательских сессий
• OAuth — делегированный доступ без передачи пароля
• Аутентификация — общий контекст проверки, кто обращается
• HashiCorp Vault — где хранить ключи командой
• URI и query-параметры — почему ключу не место в URL