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

Каждый запрос к маршрутам `/v1` передаёт ключ API мерчанта в заголовке `X-Api-Key`:

```sh
curl -H "X-Api-Key: $API_KEY" https://api.stons.io/v1/invoices/<invoice_id>
```

Ключ выдаёт оператор STONS — см. мерчанты и ключи API. Он имеет вид `sk_<16 шестнадцатеричных символов>_<43 символа base64url>`. Первая часть — публичный идентификатор ключа, вторая — секрет.

Сервис хранит не ключ, а хэш argon2id его секрета, и сравнивает хэши за постоянное время. Отсюда два следствия:

- утерянный ключ нельзя восстановить, только выпустить новый;
- ключ показывается один раз, в момент выпуска, — сохраните его в менеджер секретов.

Ключ предназначен только для запросов сервер-сервер. Он не должен попадать в браузер, мобильное приложение, репозиторий или логи. Ключи мерчантов изолированы: с ключом одного мерчанта не видно данных другого.

## Ошибки

| HTTP | `error.code` | Когда |
| --- | --- | --- |
| 401 | `unauthorized` | Заголовка нет, ключ неверного формата, неизвестен, отозван или секрет не совпадает. Причина намеренно не уточняется |
| 403 | `merchant_disabled` | Ключ верный, но мерчант отключён оператором |
| 429 | `rate_limited` | Превышен лимит запросов. Заголовок `Retry-After` — через сколько секунд повторить |

## Лимиты запросов

Число запросов в минуту ограничено дважды: для каждого IP-адреса и для каждого ключа API. Значения задаёт оператор (`API_RATE_LIMIT_PER_IP`, `API_RATE_LIMIT_PER_KEY`). Лимит по IP действует и на запросы с неверным ключом. Каждый ответ `/v1` содержит заголовки `x-ratelimit-limit`, `x-ratelimit-remaining` и `x-ratelimit-reset`.

## Ротация

У мерчанта может быть несколько действующих ключей одновременно. Замена ключа проходит без простоя: оператор выпускает новый ключ, мерчант переключается, оператор отзывает старый. Отозванный ключ перестаёт приниматься в течение 60 секунд.

## Сеть

API мерчантов отвечает по адресу `https://api.stons.io/v1`. В боевой установке перед ним стоит HTTPS-прокси: снаружи доступны только маршруты `/v1`, любой другой путь отвечает `404`, а запрос по `http://` перенаправляется кодом `308` на `https://`. Заголовок с ключом к моменту перенаправления уже ушёл по сети открытым текстом, поэтому в клиенте указывайте адрес с `https://`. Как устроен прокси — HTTPS.

Маршруты `/admin/v1` предназначены консоли оператора, а `/cabinet/v1` — приложению кабинета, а не интеграции мерчанта; снаружи недоступны и те и другие — см. административный API и API кабинета.