Перейти к содержимому

Аутентификация и права

секретный ключ интеграции ──> POST /v1/auth/login ──> access_token + refresh_token
│
POST /v2/auth/refresh <─────────┘ когда истёк

Общая схема: секретный ключ обменивается на пару токенов через POST /v1/auth/login, запросы идут с access_token, при истечении пара обновляется через POST /v2/auth/refresh, при неудачном обновлении выполняется повторный вход по секретному ключу

Из методов этой документации только эти два работают без токена. Все остальные запросы идут с заголовком:

Authorization: Bearer <access_token>

Запрос с токеном: GET с заголовком Authorization Bearer access_token, при валидном токене ответ 200, при истёкшем 401 Token is expired

У входа по секретному ключу сроки заданы в коде и не зависят от настроек компании:

Токен Срок В ответе логина
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-токен использовать больше нельзя.

Обновление пары токенов: POST /v2/auth/refresh с refresh_token, в ответ новые access_token и refresh_token, старая пара заменяется

Ошибки обновления приходят кодом 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-токен годен, иначе войти заново по секретному ключу, затем повторить исходный запрос.

Обработка 401: если refresh_token валиден, запрос POST /v2/auth/refresh, иначе повторный вход по секретному ключу, затем повтор исходного запроса

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