v2/swagger.yaml

@@ -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
 
-    ---
+    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.
-
-    # Авторизация по личному 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-сессией.
   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: |
+    description: Methods for managing personal API tokens (PATs) for server-to-server access. Requires "api-tokens-manage" permission.
-      Личные API-токены (Personal Access Tokens) для серверных интеграций.
-      Юзер управляет только своими токенами. Permission `api-tokens-manage`.
-      Management-эндпоинты доступны **только под обычной session-авторизацией**
-      (Bearer запрещён). См. секцию «Авторизация по личному API-токену» выше.
   - name: admin-user-api-token
-    description: |
+    description: Methods for admin oversight of personal API tokens. Requires "api-tokens-admin" permission.
-      Админский обзор и отзыв любых PAT тенанта. Permission `api-tokens-admin`.
-      Plain-секрет недоступен — виден только `token_prefix`.
 
 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` опционален; если задан, должен быть не в прошлом
+        ### How to use the token
-        (валидируется по началу текущего дня). Токен работает весь
-        указанный день включительно (23:59:59).
 
-        Доступно только под 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: |
+      description: 'Personal Access Token. Header: "Authorization: Bearer hrb_<token>". See user-api-token methods for details.'
-        Personal Access Token (постоянный API-токен пользователя). Заголовок:
-        `Authorization: Bearer hrb_<32 url-safe>`. Tenant авторезолвится по
-        `Host`, `x-hrbox-tenant-id` опционален. Работает только на `/api/v2/*`.
-        Токен наследует все права юзера, под которым выпущен (granular scopes
-        не поддерживаются). Подробности — в описании API.
   schemas:
     httpJsonResponse:
       type: object