2026-05-22 12:42:09 +00:00
1 changed files with 75 additions and 101 deletions
@@ -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