diff --git a/v2/swagger.yaml b/v2/swagger.yaml index fcff3e6..c29476c 100644 --- a/v2/swagger.yaml +++ b/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`) - is returned only in this response and cannot be recovered later** — - store it immediately. + Создаёт PAT для текущего юзера. **Plain-секрет (`data.plain`) + возвращается только в этом ответе и больше нигде не доступен** — + сохраните его сразу. - ### 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 - an HMAC-SHA-256 hash and the visible 12-char prefix (`hrb_xxxxxxxx`). + Формат: `hrb_` + 32 url-safe символа (всего 36). В БД хранится + только HMAC-SHA-256 хеш и видимый 12-символьный префикс + (`hrb_xxxxxxxx`). - Bearer is accepted on **`/api/v2/*` only**. It is ignored on - `/api/v1/*`, `/api/v3/*`, `/admin/*` and regular web pages. + Bearer принимается **только на `/api/v2/*`**. На `/api/v1/*`, + `/api/v3/*`, `/admin/*` и обычных веб-страницах игнорируется. - 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. + Tenant авторезолвится по `Host`-заголовку, поэтому + `x-hrbox-tenant-id` и `x-hrbox-tenant-domain` **необязательны**. + Если передаёте — будут строго провалидированы (невалидный + идентификатор → 400). `x-hrbox-session-id` / `x-hrbox-session-code` + при Bearer-аутентификации **не нужны**. - ### Scopes and permissions + ### Права и scopes - ⚠️ **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. + ⚠️ **Гранулярных scopes у токена нет.** Токен наследует **все + права** того юзера, под которым выпущен. Для интеграции заведите + отдельного системного пользователя и выдайте ему ровно те права, + которые требуются (например, `wallets-transactions` для + `/api/v2/admin/wallet*`). Не используйте свой личный аккаунт. - ### 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. + - Юзер отзывает свой токен через `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. - ### When a valid token still returns 401 + ### Когда валидный токен всё равно даёт 401 - `User::findIdentityByAccessToken` also runs `User::isValidForDisplay()`, - so a live, non-revoked, non-expired token returns `401 Login Required` - if the owner has: + `User::findIdentityByAccessToken` дополнительно вызывает + `User::isValidForDisplay()`, поэтому живой, не отозванный и не + истёкший токен отдаёт `401 Login Required`, если у владельца: - - `is_hidden = true` (hidden by an admin), or - - `reg_status_id` is not in `RegStatus::validForDisplay()` - (e.g. `INVITED`, `BLOCKED`, etc.). + - `is_hidden = true` (юзер скрыт администратором), либо + - `reg_status_id` не входит в `RegStatus::validForDisplay()` + (например `BLOCKED`). - Make sure the integration user is `is_hidden=false` and in an active - registration status. + Для системного юзера-интегратора убедитесь, что он `is_hidden=false` + и в активном reg-статусе. - ### Token management endpoints reject Bearer + ### Управление токенами под 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. + Management-эндпоинты (`/user-api-token*`, `/admin/user-api-token*`) + отдают `403`, если запрос аутентифицирован Bearer-токеном — нельзя + выпускать или отзывать токены от имени токена. Управляйте только + под обычной web-сессией. --- - This endpoint itself is also session-only (Bearer → 403). + Сам этот эндпоинт тоже доступен только под session-авторизацией + (Bearer → 403). operationId: userApiTokenCreate security: - SessionAuth: []