Авторизация
Запросы выполняются от имени пользователя. Набор доступных методов определяется правами его роли — отдельной «интеграционной» модели прав в системе нет.
Заведите для интеграции отдельную учётную запись с ролью, содержащей только необходимые разрешения. Так интеграцию можно отключить, не затрагивая работу людей.
Заголовок запроса
Токен передаётся в заголовке каждого запроса:
Authorization: Bearer <ваш_токен>
Поддерживается и базовая авторизация — она удобна для разовой проверки, но для постоянной интеграции используйте токен.
Вход по логину и паролю
POST /api/v1/login
Content-Type: application/json
{ "login": "integration", "password": "..." }
В ответе приходят токены:
| Поле | Назначение |
|---|---|
access_token | Токен доступа для заголовка Authorization |
refresh_token | Токен обновления пары |
two_factor_auth_required | Признак того, что нужен второй фактор |
temp_token, masked_phone, code_ttl | Данные для подтверждения второго фактора |
Если two_factor_auth_required равен true, вход завершается отдельным запросом подтверждения. Для интеграционной учётной записи второй фактор обычно не включают.
Обновление пары выполняется методом POST /api/v1/login/update, завершение сеанса — POST /api/v1/logout.
Помимо локального входа поддерживается авторизация через LDAP — параметры уточняются при подключении.
Долгоживущие токены
Для интеграций удобнее не хранить пароль, а выпустить именованный токен:
| Метод | Действие |
|---|---|
GET /api/v1/users/me/tokens | Список выпущенных токенов |
POST /api/v1/users/me/tokens | Выпустить токен |
DELETE /api/v1/users/me/tokens/{id} | Отозвать токен |
При выпуске указываются имя токена и, при необходимости, дата истечения:
{ "name": "erp-sync", "expire_in": "2027-01-01T00:00:00Z" }
Значение токена возвращается один раз — в ответе на создание. Повторно его получить нельзя: если значение утеряно, отзовите токен и выпустите новый.
Отозванные токены попадают в список недействительных и перестают приниматься сразу, не дожидаясь истечения срока.
Коды ответа
| Код | Причина |
|---|---|
401 | Токен отсутствует, истёк или отозван |
403 | Токен верный, но у роли нет нужного разрешения |
Различайте эти коды в интеграции: 401 требует переполучения токена, 403 — изменения прав роли, и повторные попытки его не исправят.
Рекомендации по безопасности
- Храните токен в секрет-хранилище, не коммитьте в репозитории.
- Выдавайте интеграции минимально необходимые права — см. Роли.
- Задавайте срок истечения вместо бессрочного токена.
- Ротируйте токены при смене ответственных.
- Отзывайте неиспользуемые токены: каждый из них — лишняя точка доступа.
- Заводите отдельный токен на каждую интеграцию, чтобы отзыв одной не ломал остальные.
Действия под интеграционной учётной записью попадают в журнал действий наравне с действиями людей.