Доступ и сущности

Пользователи и сессии

Получение и редактирование профиля пользователя, требования к загрузке аватаров и баннеров, управление активными сессиями.

Эндпоинты под /v1/users позволяют получать публичные и полные профили, обновлять данные и изображения профиля, просматривать права и управлять активными сессиями. Все защищённые маршруты принимают как Bearer JWT, так и X-Api-Key.

Получение профиля

МетодПутьАвторизацияЧто возвращает
GET/v1/users/@meJWT / pat (users.profile:read:self)Полный профиль текущего пользователя
GET/v1/users?username=...ОпциональнаяПолный профиль владельцу или при наличии users.profile:read, иначе — публичный профиль
GET/v1/users/{uuid}ОпциональнаяТо же правило видимости по UUID

Публичный профиль vs полный профиль

ПолеПубличный (UserGetResponsePublic)Полный (UserGetResponse)
id, username, avatar, banner, groupsДаДа
email, firstname, lastname, middlename—Да
permissions—Да
departments—Да (для чужого профиля отфильтровано по правилам видимости отделов)
Эндпоинты GET /v1/users и GET /v1/users/{uuid} защищены лимитом 60 запросов в минуту на субъект (или на IP-адрес для анонимных вызовов).

Редактирование профиля

PATCH /v1/users/{uuid}
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "username": "new_nick",
  "firstname": "Иван",
  "lastname": "Иванов"
}
  • Необходимо передать хотя бы одно поле; отсутствующие поля не изменяются.
  • Допустимые поля и ограничения:
    • username — от 3 до 32 символов, паттерн ^[a-zA-Z0-9_-]{3,32}$;
    • email — валидный email до 320 символов;
    • firstname, lastname — от 1 до 128 символов;
    • middlename — до 128 символов.
  • Пользователь может изменять собственный профиль (users.profile:write:self), администратор — любой (users.profile:write).
  • При конкурентном обновлении одного профиля может вернуться 409 Conflict — запрос безопасно повторить.

Просмотр прав пользователя

GET /v1/users/{uuid}/permissions

Возвращает итоговый плоский список строк прав (string[]). Доступно владельцу (users.permissions:read:self) либо вызывающему с глобальным/делегированным правом authservice.users.permissions:read.

Загрузка аватара и баннера

PATCH /v1/users/{uuid}/avatar
PATCH /v1/users/{uuid}/banner
Content-Type: multipart/form-data

Изображения валидируются и автоматически конвертируются в WebP:

ПараметрАватар (avatar)Баннер (banner)
Допустимые типыimage/jpeg, image/png, image/webpimage/jpeg, image/png, image/webp
Максимальный размер файла5 МБ10 МБ
ПропорцииКвадрат (допуск ±2 px)Альбомная ориентация (width >= height)
Разрешение входаот 128×128 до 4096×4096от 1536×512 до 10000×5000
Итоговый форматWebP, до 1024×1024 (кроп, без апскейла)WebP, до 3000×1000 (кроп, без апскейла)
Rate limit3 загрузки за 5 минут3 загрузки за 5 минут

При несоответствии требованиям возвращается 400 Bad Request с error: "invalid_image".

Управление сессиями

МетодПутьПараметрыОписание
GET/v1/users/{uuid}/sessions?onlyActive=true (по умолчанию true)Список сессий пользователя (id, created_at, updated_at, expires_at, ip_addresses, user_agent)
DELETE/v1/users/{uuid}/sessions/{sessionId}—Принудительный отзыв конкретной сессии (204 No Content)

Владелец работает со своими сессиями по базовым правам :self; доступ к чужим сессиям требует authservice.users.sessions:read / authservice.users.sessions:delete (глобально или со скоупом {uuid}).

Участие в отделах

GET /v1/users/{userId}/departments

Возвращает список отделов пользователя и его ролей в них. Для собственного userId возвращаются все участия; для чужого — только те, которые вызывающий имеет право видеть по правилам видимости отделов.