Пользователи и сессии
Эндпоинты под /v1/users позволяют получать публичные и полные профили, обновлять данные и изображения профиля, просматривать права и управлять активными сессиями. Все защищённые маршруты принимают как Bearer JWT, так и X-Api-Key.
Получение профиля
| Метод | Путь | Авторизация | Что возвращает |
|---|---|---|---|
GET | /v1/users/@me | JWT / 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/webp | image/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 limit | 3 загрузки за 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 возвращаются все участия; для чужого — только те, которые вызывающий имеет право видеть по правилам видимости отделов.