Аутентификация и права
Цепочка
Заголовок раздела «Цепочка»секретный ключ интеграции ──> POST /v1/auth/login ──> access_token + refresh_token │ POST /v2/auth/refresh <─────────┘ когда истёк
Из методов этой документации только эти два работают без токена. Все остальные запросы идут с заголовком:
Authorization: Bearer <access_token>
Срок жизни токенов
Заголовок раздела «Срок жизни токенов»У входа по секретному ключу сроки заданы в коде и не зависят от настроек компании:
| Токен | Срок | В ответе логина |
|---|---|---|
access_token |
15 суток | expires_in: 1296000 (секунды) |
refresh_token |
30 суток | приходит полем refresh_token; собственного expires_in у него нет |
Обновление токена
Заголовок раздела «Обновление токена»curl -X POST 'https://api-admin.billz.ai/v2/auth/refresh' \ -H 'Content-Type: application/json' \ -H 'platform-id: 7d4a4c38-dd84-4902-b744-0488b80a4c01' \ -d '{ "refresh_token": "..." }'В ответ приходит новая пара токенов с полями expires_in и refresh_expires_in.
Старый refresh-токен использовать больше нельзя.

Ошибки обновления приходят кодом 400 (RFC 6749 §5.2): 401 от обычного метода означает
истёкший access-токен, 400 от обновления — непригодный refresh-токен.
В поле error приходит код стандарта: invalid_request, invalid_grant, unauthorized_client;
внутренний сбой — 500 с server_error.
Доступ ключа устроен из двух независимых уровней.
Уровень 1 — маршрут. Пара «HTTP-метод + шаблон маршрута» должна найтись в фиксированном списке маршрутов, одинаковом для всех компаний. Полный список — что может ключ интеграции.
Уровень 2 — право роли. У ключа есть своя роль. Её переключатели доступов проверяются уже при выполнении разрешённого запроса и решают, что вернётся в ответе и пройдёт ли операция: права роли ключа.
Сравнивается шаблон маршрута (/v2/transfer/:id/add) и HTTP-глагол: PUT там, где
зарегистрирован PATCH, не пройдёт; значения ID на проверку не влияют.
Права кэшируются на 20 минут; изменение роли сбрасывает кэш.
Что означают коды ответа
Заголовок раздела «Что означают коды ответа»Тело ошибки обычно {"code": ..., "message": ..., "error": ..., "data": null}.
Причина различается по паре message + error:
| Код | message / error |
Что случилось |
|---|---|---|
401 |
token error |
токен не разбирается: обрезан, испорчен, чужая подпись |
401 |
token expired / token has been expired |
истёк — требуется обновление |
401 |
unauthorized / refresh token used as access |
в Authorization подставлен refresh-токен |
401 |
unauthorized / session not found, session revoked |
сессия закрыта или отозвана — нужен новый логин |
401 |
unauthorized / mismatch platform-id with token info |
platform-id не тот, с которым выдан токен |
401 |
unauthorized / user is not active, user has been expired |
ключ отключён или у него вышел срок |
403 |
forbidden / access denied |
маршрута нет в списке, доступном ключу |
403 |
blocked / company is blocked |
заблокирована компания целиком |
Разбор этих случаев — 403 и 404.
Порядок действий клиента при 401: обновить пару, пока refresh-токен годен, иначе войти
заново по секретному ключу, затем повторить исходный запрос.

Практика
Заголовок раздела «Практика»- Секретный ключ хранится в защищённом хранилище.
access_tokenобновляется до истечения срока.- Обновление выполняется из одного места.
- На каждую интеграцию заводится отдельный ключ.