API-ключ

API-ключ (API key) — один из наиболее простых методов аутентификации для REST API. Клиент получает уникальную строку (обычно 32–64 символа, случайная последовательность или UUID) и включает её в каждый запрос к API. Сервер проверяет ключ и определяет, имеет ли клиент право на запрошенное действие.

Как работает

Способы передачи API-ключа:

• HTTP-заголовок (предпочтительно) — Authorization: ApiKey sk-abc123... или кастомный заголовок типа X-API-Key: sk-abc123.
• Query-параметр — https://api.example.com/data?api_key=sk-abc123. Небезопасно: ключ попадает в логи сервера и browser history.
• Тело запроса (POST) — {"api_key": "sk-abc123"}. Использовалось в ранних API, сейчас редко.

Жизненный цикл API-ключа:

1. Генерация: пользователь создаёт ключ в личном кабинете или через CLI.
2. Хранение: сервер хранит хэш ключа (bcrypt, SHA-256), не сам ключ. Пользователь видит ключ один раз при создании.
3. Передача: клиент включает ключ в каждый запрос по HTTPS.
4. Проверка: middleware сравнивает хэш ключа из запроса с хранимым хэшем, определяет владельца и его права.
5. Ротация: ключи имеют срок действия или ротируются вручную при компрометации.

API-ключи vs альтернативы:

• API-ключ — прост в реализации, подходит для server-to-server. Не содержит информации о пользователе (непрозрачный токен).
• Bearer-токен / JWT — самодостаточный токен с claims (данными о пользователе). Не требует обращения к БД для декодирования, но сложнее отозвать.
• OAuth 2.0 — стандарт для делегированного доступа: пользователь разрешает приложению действовать от своего имени без передачи пароля.

История

API-ключи появились с первыми коммерческими веб-API в начале 2000-х годов: Google Maps API (2005), Amazon Web Services (2006), Twitter API (2006). До этого API-аутентификация строилась на Basic Auth (RFC 7617, HTTP-заголовок Authorization с base64). REST-принципы (Roy Fielding, 2000) не специфицировали конкретный метод аутентификации, что привело к разнообразию подходов. Сегодня для публичных API стандартом считается OAuth 2.0 + OpenID Connect; API-ключи — для серверного использования и простых интеграций.

На что обращать внимание

Никогда не передавайте API-ключи в URL-параметрах и не коммитьте их в Git. Используйте переменные окружения или секреты в CI/CD. Реализуйте rate limiting по API-ключу: без него один скомпрометированный ключ может перегрузить ваш API. При подозрении на утечку ключ следует немедленно отозвать и сгенерировать новый. Для хранения ключей в приложении рекомендуется менеджер секретов (HashiCorp Vault, AWS Secrets Manager, Doppler).

На что обращать внимание при работе с API-ключами на хостинге

API-ключи — стандартный способ аутентификации в хостинг-провайдерах: Hetzner API, Cloudflare API, VK Cloud API. Ключи используются в Terraform-конфигурации для управления инфраструктурой через код. Храните ключи в переменных окружения или Secret Manager, никогда в коде или git-репозитории. Ротация ключей — минимум раз в год или при увольнении сотрудника с доступом.

Типичные ошибки при работе с API-ключами

• Ключ с полными правами (owner scope) вместо минимально необходимых — компрометация даёт полный контроль над аккаунтом хостинга.
• Один ключ для всех сред (dev/staging/production) — ротация требует изменений везде.
• API-ключ в URL-параметре (?api_key=...) — попадает в логи сервера и браузерную историю.
• Отсутствие мониторинга использования ключа — компрометация не обнаруживается вовремя.