H-3657: PAT how-to → описание метода create, тэги/info → короткие EN #35
+74
-104
@@ -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,76 @@ paths:
|
||||
/user-api-token/create:
|
||||
post:
|
||||
tags: [user-api-token]
|
||||
summary: Создать новый API-токен (plain возвращается один раз)
|
||||
summary: Create a new personal API token (plain secret is returned once)
|
||||
description: |
|
||||
Создаёт PAT для текущего юзера. **Plain-секрет (`data.plain`)
|
||||
возвращается только в этом ответе и больше нигде не доступен** —
|
||||
сохраните его сразу.
|
||||
Creates a PAT for the current user. **The plain secret (`data.plain`)
|
||||
is returned only in this response and cannot be recovered later** —
|
||||
store it immediately.
|
||||
|
||||
`expires_at` опционален; если задан, должен быть не в прошлом
|
||||
(валидируется по началу текущего дня). Токен работает весь
|
||||
указанный день включительно (23:59:59).
|
||||
### How to use the token
|
||||
|
||||
Доступно только под session-авторизацией (запрос под Bearer → 403).
|
||||
Sign every request with the `Authorization` header:
|
||||
|
||||
```
|
||||
Authorization: Bearer hrb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
Format: `hrb_` + 32 url-safe chars (36 chars total). The DB stores only
|
||||
an HMAC-SHA-256 hash and the visible 12-char prefix (`hrb_xxxxxxxx`).
|
||||
|
||||
Bearer is accepted on **`/api/v2/*` only**. It is ignored on
|
||||
`/api/v1/*`, `/api/v3/*`, `/admin/*` and regular web pages.
|
||||
|
||||
Tenant is auto-resolved from the request `Host`, so `x-hrbox-tenant-id`
|
||||
and `x-hrbox-tenant-domain` are **optional**. If provided, they are
|
||||
strictly validated (invalid tenant → 400). `x-hrbox-session-id` /
|
||||
`x-hrbox-session-code` are **not needed** with Bearer.
|
||||
|
||||
### Scopes and permissions
|
||||
|
||||
⚠️ **There are no granular scopes.** The token inherits **all
|
||||
permissions** of the user it was issued for. For integrations, create
|
||||
a dedicated system user and grant only the required permissions
|
||||
(e.g. `wallets-transactions` for `/api/v2/admin/wallet*`). Do not use
|
||||
your personal account.
|
||||
|
||||
### Lifecycle and revocation
|
||||
|
||||
- The user revokes their token via `POST /api/v2/user-api-token/revoke`
|
||||
or from the UI.
|
||||
- An admin with `api-tokens-admin` can list/revoke any token in the
|
||||
tenant via `/api/v2/admin/user-api-token*`. The plain secret is
|
||||
**never** visible to admins, only the prefix.
|
||||
- When a user is blocked (`reg_status_id = BLOCKED`), all their tokens
|
||||
are auto-revoked. They are **not** restored on unblock — new ones
|
||||
must be issued.
|
||||
- If `expires_at` is set, the token stops working after that date
|
||||
(status `EXPIRED`). `expires_at` is optional and must not be in the
|
||||
past (validated against the start of the current day); the token
|
||||
works through the full given day until 23:59:59.
|
||||
|
||||
### When a valid token still returns 401
|
||||
|
||||
`User::findIdentityByAccessToken` also runs `User::isValidForDisplay()`,
|
||||
so a live, non-revoked, non-expired token returns `401 Login Required`
|
||||
if the owner has:
|
||||
|
||||
- `is_hidden = true` (hidden by an admin), or
|
||||
- `reg_status_id` is not in `RegStatus::validForDisplay()`
|
||||
(e.g. `INVITED`, `BLOCKED`, etc.).
|
||||
|
||||
Make sure the integration user is `is_hidden=false` and in an active
|
||||
registration status.
|
||||
|
||||
### Token management endpoints reject Bearer
|
||||
|
||||
Management endpoints (`/user-api-token*`, `/admin/user-api-token*`)
|
||||
return `403` if called with a Bearer token — tokens cannot be issued
|
||||
or revoked from a token. Use a regular web session for management.
|
||||
|
||||
---
|
||||
|
||||
This endpoint itself is also session-only (Bearer → 403).
|
||||
operationId: userApiTokenCreate
|
||||
security:
|
||||
- SessionAuth: []
|
||||
@@ -7566,12 +7541,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