diff --git a/v2/swagger.yaml b/v2/swagger.yaml
index 33bae1d..537ba02 100644
--- a/v2/swagger.yaml
+++ b/v2/swagger.yaml
@@ -87,6 +87,20 @@ info:
     - Если у токена выставлен `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*`)