Аутентификация
Каждый запрос к маршрутам /v1 передаёт ключ API мерчанта в заголовке X-Api-Key:
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 кабинета.