<!-- /docs/authentication (ru) -->

# Аутентификация

## Один ключ на всё

Аутентификация — партнёрский API-ключ формата `fl_live_<64 hex>`. Один и тот же ключ работает на всех эндпоинтах: генерация, биллинг, управление ключами.

Передавайте ключ одним из двух способов:

```bash
# Заголовок X-API-Key (рекомендуется)
curl -H "X-API-Key: $FRANKLAB_KEY" https://apergrex.ru/franklab/api/v1/billing/balance

# Или Authorization: Bearer
curl -H "Authorization: Bearer $FRANKLAB_KEY" https://apergrex.ru/franklab/api/v1/billing/balance
```

## Статусы ответов

| Код | Причина | Что делать |
|---|---|---|
| 401 | Ключ отсутствует, неизвестен или деактивирован | Проверьте ключ; новый выпускается в кабинете (**Настройки → API**) |
| 403 | Передан legacy service-ключ | Нужен именно партнёрский `fl_live_`-ключ |
| 429 | Превышен лимит запросов | Повторите позже; по умолчанию 60 запросов/мин на партнёра |

## Лимиты

Поверх лимита партнёра действует общий лимит шлюза (100 запросов/мин на IP). Ответ 429 безопасно повторять с задержкой.

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

- Ключ хранится на сервере только как хэш — «показать снова» невозможно; потерянный ключ отзывают и выпускают новый.
- Передавайте ключ только по HTTPS, никогда — в URL, логах или клиентском коде.
- Ключ можно отозвать мгновенно из сессии кабинета: `DELETE /v1/billing/api-keys/{id}` (или страница **Настройки → API**). Отзыв ключа не требует самого ключа — и ключ не может создать себе замену.
- Заведите отдельный ключ на каждую интеграцию — метка помогает отличать их в списке.

## Управление ключами

Чтение списка ключей — по API-ключу. Выпуск и отзыв — **только в сессии кабинета** (cookie партнёра): API-ключ не может выпускать новые ключи, поэтому скомпрометированный ключ отзывается полностью — у него нет «потомков», которые пережили бы отзыв. Это то же доверие, что у страницы **Настройки → API**.

```bash
# список (только префиксы, сырое значение не возвращается) — по API-ключу
curl -H "X-API-Key: $FRANKLAB_KEY" https://apergrex.ru/franklab/api/v1/billing/api-keys
```

Создать (`POST /v1/billing/api-keys`) и отозвать (`DELETE /v1/billing/api-keys/{id}`) ключ можно из кабинета: **Настройки → API** — или тем же запросом из залогиненной сессии кабинета (cookie `franklab_token`).