Merge branch 'feature/H-3657' into 'master'
H-3657: PAT how-to → описание метода create, тэги/info → короткие EN See merge request hrbox-public/api!35
This commit was merged in pull request #35.
This commit is contained in:
+75
-101
@@ -28,85 +28,7 @@ info:
|
||||
{sessionSecret} - you will get this form /mobile/auth method
|
||||
the last one (x-hrbox-embed) is for opening web pages in WebView to remove website footer and header
|
||||
|
||||
---
|
||||
|
||||
# Авторизация по личному API-токену (Personal Access Token, PAT)
|
||||
|
||||
Для серверных интеграций (web-zaim и т.п.) удобнее не держать сессию,
|
||||
а использовать постоянный токен. Токен работает **только на `/api/v2/*`**
|
||||
(для `/api/v1/*`, `/api/v3/*`, `/admin/*` и веб-страниц — игнорируется).
|
||||
|
||||
## Получение токена
|
||||
|
||||
1. Юзеру, от имени которого будет работать интеграция, нужно право
|
||||
`api-tokens-manage` (выдаётся точечно администратором).
|
||||
2. Юзер открывает `/profile/settings/api-tokens` в веб-интерфейсе и жмёт
|
||||
«Создать токен» — задаёт название и (опционально) дату истечения.
|
||||
Plain-секрет **показывается один раз** в этом окне, после закрытия
|
||||
восстановить нельзя.
|
||||
3. Альтернативно — `POST /api/v2/user-api-token` под session-авторизацией
|
||||
(см. ниже про management-эндпоинты). Plain также возвращается
|
||||
один раз в поле `data.plain`.
|
||||
|
||||
Формат plain-токена: `hrb_` + 32 url-safe символов = 36 символов всего.
|
||||
В БД хранится только HMAC-SHA-256 хеш и видимый префикс (первые 12
|
||||
символов с `hrb_`).
|
||||
|
||||
## Использование токена
|
||||
|
||||
Подписывайте каждый запрос заголовком `Authorization`:
|
||||
|
||||
```
|
||||
Authorization: Bearer hrb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
Tenant авторезолвится по `Host`-заголовку запроса, поэтому
|
||||
`x-hrbox-tenant-id` / `x-hrbox-tenant-domain` **необязательны**.
|
||||
Если всё же передаёте — будут строго провалидированы, невалидный
|
||||
идентификатор тенанта → 400. `x-hrbox-session-id` / `x-hrbox-session-code`
|
||||
при Bearer-аутентификации **не нужны**.
|
||||
|
||||
## Права и scopes
|
||||
|
||||
⚠️ **Гранулярных scopes у токена нет.** Токен наследует **все права того
|
||||
юзера**, под которым выпущен. Это означает что для интеграции нужно
|
||||
создать **отдельного системного пользователя** и выдать ему ровно те
|
||||
права, которые требуются (например, `wallets-transactions` для нового
|
||||
`/api/v2/admin/wallet*`). Не используйте свой личный аккаунт.
|
||||
|
||||
## Отзыв и жизненный цикл
|
||||
|
||||
- Юзер отзывает свой токен через `POST /api/v2/user-api-token/revoke`
|
||||
(или из UI).
|
||||
- Администратор с правом `api-tokens-admin` может посмотреть/отозвать
|
||||
любой токен тенанта через `/api/v2/admin/user-api-token*`. Plain
|
||||
админу **никогда не виден**, только префикс.
|
||||
- При блокировке юзера (`reg_status_id = BLOCKED`) все его токены
|
||||
автоматически отзываются. При разблокировке **обратно не восстанавливаются** —
|
||||
нужно выпускать новые.
|
||||
- Если у токена выставлен `expires_at` — после этой даты он перестаёт
|
||||
работать сам (статус `EXPIRED`).
|
||||
|
||||
## Когда валидный токен всё равно даёт 401
|
||||
|
||||
`User::findIdentityByAccessToken` дополнительно вызывает
|
||||
`User::isValidForDisplay()`, поэтому даже корректный live-токен
|
||||
отдаёт `401 Login Required`, если у владельца:
|
||||
|
||||
- `is_hidden = true` (юзер скрыт администратором), либо
|
||||
- `reg_status_id` **не входит** в `RegStatus::validForDisplay()`
|
||||
(например `INVITED`, `BLOCKED` и пр.).
|
||||
|
||||
Для системного юзера-интегратора убедитесь, что он `is_hidden=false`
|
||||
и в активном reg-статусе, иначе токен не пройдёт ни на одном
|
||||
`/api/v2/*` эндпоинте.
|
||||
|
||||
## Управление токенами под Bearer запрещено
|
||||
|
||||
Management-эндпоинты (`/user-api-token*`, `/admin/user-api-token*`)
|
||||
отдают `403`, если запрос аутентифицирован Bearer-токеном — нельзя
|
||||
выпускать или отзывать токены от имени токена. Управляйте только
|
||||
под обычной web-сессией.
|
||||
For server-to-server integrations /api/v2/* endpoints also accept a Personal Access Token via "Authorization: Bearer hrb_<token>". See user-api-token methods for issuing and lifecycle details.
|
||||
contact:
|
||||
email: yuriy@hrbox.io
|
||||
|
||||
@@ -142,21 +64,15 @@ tags:
|
||||
- name: kedo
|
||||
description: Методы для работы с КЭДО.
|
||||
- name: admin-wallet
|
||||
description: Админский API кошельков сотрудников (read-only). Permission `wallets-transactions`, требует `enableWallet=true` у тенанта.
|
||||
description: Methods for admin access to employee wallets (read-only). Requires "wallets-transactions" permission and enableWallet tenant flag.
|
||||
- name: admin-wallet-transaction
|
||||
description: Админский API транзакций кошелька — проведение начислений/списаний (form/excel) и просмотр.
|
||||
description: Methods for admin wallet transactions — manual and excel-based credit/debit.
|
||||
- name: file-processing
|
||||
description: Статусы асинхронных обработок файлов (excel-импорт/экспорт, архивы). Видны только записи текущего пользователя.
|
||||
description: Methods for polling async file processing (excel import/export, archives). Scoped to current user's files.
|
||||
- name: user-api-token
|
||||
description: |
|
||||
Личные API-токены (Personal Access Tokens) для серверных интеграций.
|
||||
Юзер управляет только своими токенами. Permission `api-tokens-manage`.
|
||||
Management-эндпоинты доступны **только под обычной session-авторизацией**
|
||||
(Bearer запрещён). См. секцию «Авторизация по личному API-токену» выше.
|
||||
description: Methods for managing personal API tokens (PATs) for server-to-server access. Requires "api-tokens-manage" permission.
|
||||
- name: admin-user-api-token
|
||||
description: |
|
||||
Админский обзор и отзыв любых PAT тенанта. Permission `api-tokens-admin`.
|
||||
Plain-секрет недоступен — виден только `token_prefix`.
|
||||
description: Methods for admin oversight of personal API tokens. Requires "api-tokens-admin" permission.
|
||||
|
||||
paths:
|
||||
/mobile/bind/{id}/{token}:
|
||||
@@ -7392,17 +7308,80 @@ paths:
|
||||
/user-api-token/create:
|
||||
post:
|
||||
tags: [user-api-token]
|
||||
summary: Создать новый API-токен (plain возвращается один раз)
|
||||
summary: Создать новый API-токен (plain-секрет возвращается один раз)
|
||||
description: |
|
||||
Создаёт PAT для текущего юзера. **Plain-секрет (`data.plain`)
|
||||
возвращается только в этом ответе и больше нигде не доступен** —
|
||||
сохраните его сразу.
|
||||
|
||||
`expires_at` опционален; если задан, должен быть не в прошлом
|
||||
(валидируется по началу текущего дня). Токен работает весь
|
||||
указанный день включительно (23:59:59).
|
||||
### Как пользоваться токеном
|
||||
|
||||
Доступно только под session-авторизацией (запрос под Bearer → 403).
|
||||
Подписывайте каждый запрос заголовком `Authorization`:
|
||||
|
||||
```
|
||||
Authorization: Bearer hrb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
Формат: `hrb_` + 32 url-safe символа (всего 36). В БД хранится
|
||||
только HMAC-SHA-256 хеш и видимый 12-символьный префикс
|
||||
(`hrb_xxxxxxxx`).
|
||||
|
||||
Bearer принимается **только на `/api/v2/*`**. На `/api/v1/*`,
|
||||
`/api/v3/*`, `/admin/*` и обычных веб-страницах игнорируется.
|
||||
|
||||
Tenant авторезолвится по `Host`-заголовку, поэтому
|
||||
`x-hrbox-tenant-id` и `x-hrbox-tenant-domain` **необязательны**.
|
||||
Если передаёте — будут строго провалидированы (невалидный
|
||||
идентификатор → 400). `x-hrbox-session-id` / `x-hrbox-session-code`
|
||||
при Bearer-аутентификации **не нужны**.
|
||||
|
||||
### Права и scopes
|
||||
|
||||
⚠️ **Гранулярных scopes у токена нет.** Токен наследует **все
|
||||
права** того юзера, под которым выпущен. Для интеграции заведите
|
||||
отдельного системного пользователя и выдайте ему ровно те права,
|
||||
которые требуются (например, `wallets-transactions` для
|
||||
`/api/v2/admin/wallet*`). Не используйте свой личный аккаунт.
|
||||
|
||||
### Отзыв и жизненный цикл
|
||||
|
||||
- Юзер отзывает свой токен через `POST /api/v2/user-api-token/revoke`
|
||||
(или из UI).
|
||||
- Администратор с правом `api-tokens-admin` может посмотреть/отозвать
|
||||
любой токен тенанта через `/api/v2/admin/user-api-token*`. Plain
|
||||
админу **никогда не виден**, только префикс.
|
||||
- При блокировке юзера (`reg_status_id = BLOCKED`) все его токены
|
||||
автоматически отзываются. При разблокировке **обратно не
|
||||
восстанавливаются** — нужно выпускать новые.
|
||||
- Если выставлен `expires_at`, после этой даты токен перестаёт
|
||||
работать (статус `EXPIRED`). `expires_at` опционален, не может быть
|
||||
в прошлом (валидируется по началу текущего дня); токен работает
|
||||
весь указанный день включительно до 23:59:59.
|
||||
|
||||
### Когда валидный токен всё равно даёт 401
|
||||
|
||||
`User::findIdentityByAccessToken` дополнительно вызывает
|
||||
`User::isValidForDisplay()`, поэтому живой, не отозванный и не
|
||||
истёкший токен отдаёт `401 Login Required`, если у владельца:
|
||||
|
||||
- `is_hidden = true` (юзер скрыт администратором), либо
|
||||
- `reg_status_id` не входит в `RegStatus::validForDisplay()`
|
||||
(например `BLOCKED`).
|
||||
|
||||
Для системного юзера-интегратора убедитесь, что он `is_hidden=false`
|
||||
и в активном reg-статусе.
|
||||
|
||||
### Управление токенами под Bearer запрещено
|
||||
|
||||
Management-эндпоинты (`/user-api-token*`, `/admin/user-api-token*`)
|
||||
отдают `403`, если запрос аутентифицирован Bearer-токеном — нельзя
|
||||
выпускать или отзывать токены от имени токена. Управляйте только
|
||||
под обычной web-сессией.
|
||||
|
||||
---
|
||||
|
||||
Сам этот эндпоинт тоже доступен только под session-авторизацией
|
||||
(Bearer → 403).
|
||||
operationId: userApiTokenCreate
|
||||
security:
|
||||
- SessionAuth: []
|
||||
@@ -7566,12 +7545,7 @@ components:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: PAT
|
||||
description: |
|
||||
Personal Access Token (постоянный API-токен пользователя). Заголовок:
|
||||
`Authorization: Bearer hrb_<32 url-safe>`. Tenant авторезолвится по
|
||||
`Host`, `x-hrbox-tenant-id` опционален. Работает только на `/api/v2/*`.
|
||||
Токен наследует все права юзера, под которым выпущен (granular scopes
|
||||
не поддерживаются). Подробности — в описании API.
|
||||
description: 'Personal Access Token. Header: "Authorization: Bearer hrb_<token>". See user-api-token methods for details.'
|
||||
schemas:
|
||||
httpJsonResponse:
|
||||
type: object
|
||||
|
||||
Reference in New Issue
Block a user