v2/swagger.yaml

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