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

Раздел «Пользователи» — запросы для работы с профилем текущего авторизованного пользователя: чтение и редактирование профиля, статус присутствия, аватар, обновление и отзыв токена, выход из аккаунта. В отличие от раздела «Анонимные», почти все запросы этой группы требуют заголовок Authorization: Bearer <accessToken>, полученный через «OAuth2» — исключение единственное, см. «Обновить токен».

Объект UserResponse

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

Поле	Тип	Описание
id	string	Идентификатор пользователя.
username	string	Уникальное имя пользователя.
email	string	Email пользователя.
displayName	string	Отображаемое имя.
description	string	Описание профиля («о себе»).
status	string	Произвольный текстовый статус, который пользователь установил себе сам (не путать с userStatus — присутствием).
preferredLanguage	string	Предпочитаемый язык интерфейса.
createdAt	string	Когда создан аккаунт (ISO8601).
updatedAt	string	Когда профиль обновлялся в последний раз (ISO8601).
lastActivity	string	Время последней активности пользователя (ISO8601).
isConfirmed	boolean	Подтверждён ли аккаунт (например, email).
isBot	boolean	Признак бот-аккаунта.
subscriptionType	string	Тип подписки пользователя.
avatarUrl	string	URL аватара.
bannerUrl	string	URL баннера профиля.
userStatus	UserStatus	Текущий статус присутствия.

UserStatus

Значение	Описание
ONLINE	Пользователь на связи.
OFFLINE	Пользователь не на связи.
DO_NOT_DISTURB	Не беспокоить.
INVISIBLE	Пользователь выглядит офлайн для остальных, оставаясь фактически на связи.

Объект ошибки

При любой ошибке вместо 200 OK возвращается default-ответ:

Поле	Тип	Описание
code	integer	Числовой код ошибки (google.rpc.Code).
message	string	Человекочитаемое описание ошибки.
details	array	Дополнительные структурированные детали ошибки (google.protobuf.Any); в большинстве случаев пуст.

{
  "code": 16,
  "message": "access token is missing or invalid",
  "details": []
}

---

Токен

Обновить токен

POST/v1/users/token/refresh

Обменивает refreshToken на новую пару токенов — без повторного интерактивного входа. Это единственный запрос в разделе «Пользователи», который не требует заголовка Authorization: сам refreshToken и есть подтверждение личности вызывающего.

Тело запроса

Поле	Тип	Описание
refreshToken	string	Токен обновления, полученный ранее — либо при первичном обмене кода в разделе «Анонимные», либо из ответа предыдущего вызова этого же запроса.

{
  "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ..."
}

Ответ 200 OK

Та же структура полей, что у AuthResponse: accessToken, tokenType, expiresIn, refreshToken, refreshExpiresIn, idToken, notBeforePolicy, sessionState, scope.

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ...",
  "expiresIn": 300,
  "refreshExpiresIn": 1800,
  "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ...",
  "tokenType": "Bearer",
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ...",
  "notBeforePolicy": 0,
  "sessionState": "3f1c9e2a-6b7d-4e5f-8a9b-1c2d3e4f5a6b",
  "scope": "openid profile email"
}

Старый refreshToken перестаёт действовать

После успешного обновления старая пара токенов инвалидируется — используйте refreshToken из нового ответа для следующего обновления, не тот, что был передан в запросе.

Ответ default (ошибка)

Стандартный объект ошибки — например, при истёкшем или отозванном refreshToken.

---

Профиль

Получить свой профиль

GET/v1/users/me

Возвращает профиль текущего авторизованного пользователя.

Ответ 200 OK

Объект UserResponse.

Ответ default (ошибка)

Стандартный объект ошибки.

Изменить свой профиль

POST/v1/users/me

Обновляет профиль текущего пользователя.

Тело запроса

Поле	Тип	Описание
displayName	string	Новое отображаемое имя.
description	string	Новое описание профиля.
status	string	Новый произвольный текстовый статус (см. status в UserResponse).
preferredLanguage	string	Новый предпочитаемый язык интерфейса.

{
  "displayName": "Alex",
  "description": "пишу SDK для ботов",
  "status": "занят разработкой",
  "preferredLanguage": "ru"
}

Ответ 200 OK

Обновлённый объект UserResponse.

Ответ default (ошибка)

Стандартный объект ошибки.

Изменить статус присутствия

POST/v1/users/me/status

Устанавливает статус присутствия (userStatus) текущего пользователя — отдельно от текстового status, см. «Объект UserResponse».

Тело запроса

Поле	Тип	Описание
userStatus	UserStatus	Новый статус присутствия.

{
  "userStatus": "DO_NOT_DISTURB"
}

Ответ 200 OK

Обновлённый объект UserResponse.

Ответ default (ошибка)

Стандартный объект ошибки.

---

Аватар

Загрузка аватара — двухшаговый процесс: сначала клиент запрашивает URL для загрузки файла (avatar/upload), затем сам загружает файл по этому URL и подтверждает загрузку (avatar/confirm).

Запросить загрузку аватара

POST/v1/users/me/avatar/upload

Инициирует загрузку нового аватара и возвращает предподписанный URL, на который клиент должен загрузить файл напрямую.

Тело запроса

Поле	Тип	Описание
contentType	string	MIME-тип загружаемого файла (например, image/png).
sizeBytes	integer (int64)	Размер файла в байтах.

{
  "contentType": "image/png",
  "sizeBytes": 245760
}

Ответ 200 OK

Поле	Тип	Описание
avatarId	string	Идентификатор загрузки — передаётся дальше в «Подтвердить загрузку аватара».
uploadUrl	string	URL, на который нужно загрузить файл (обычно прямым PUT-запросом с телом файла).
expiresAt	string	Время, до которого действителен uploadUrl.

{
  "avatarId": "a1b2c3d4-5e6f-4789-9abc-def012345678",
  "uploadUrl": "https://cdn.iopta.org/uploads/a1b2c3d4-5e6f-4789-9abc-def012345678?signature=...",
  "expiresAt": "2026-08-09T15:30:00Z"
}

Ответ default (ошибка)

Стандартный объект ошибки.

Подтвердить загрузку аватара

POST/v1/users/me/avatar/confirm

Подтверждает, что файл по uploadUrl из предыдущего шага загружен, и делает аватар с указанным avatarId активным аватаром пользователя.

Тело запроса

Поле	Тип	Описание
avatarId	string	Идентификатор загрузки, полученный из «Запросить загрузку аватара».

{
  "avatarId": "a1b2c3d4-5e6f-4789-9abc-def012345678"
}

Ответ 200 OK

Обновлённый объект UserResponse с новым avatarUrl.

Ответ default (ошибка)

Стандартный объект ошибки — например, если файл по uploadUrl ещё не загружен или avatarId истёк.

Получить аватар пользователя

GET/v1/users/{userId}/avatar

Возвращает URL аватара произвольного пользователя по его id.

Параметры пути

Поле	Тип	Описание
userId	string	Идентификатор пользователя, чей аватар запрашивается.

Ответ 200 OK

Поле	Тип	Описание
avatarUrl	string	URL аватара пользователя.

{
  "avatarUrl": "https://cdn.iopta.org/avatars/3fa85f64-5717-4562-b3fc-2c963f66afa6.png"
}

Ответ default (ошибка)

Стандартный объект ошибки — например, если пользователь с таким userId не найден.

Удалить аватар

DELETE/v1/users/me/avatar

Удаляет аватар текущего пользователя.

Ответ 200 OK

Обновлённый объект UserResponse с пустым avatarUrl.

---

Сессия

Выйти из аккаунта

POST/v1/users/logout

Инвалидирует refreshToken, завершая сессию, к которой он относится. Ранее выданный accessToken продолжает действовать до истечения своего expiresIn — он не отзывается немедленно, только перестаёт продлеваться этим refreshToken.

Тело запроса

Поле	Тип	Описание
refreshToken	string	Токен обновления сессии, которую нужно завершить.

{
  "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ..."
}

Ответ 200 OK

Пустой объект {}.

Ответ default (ошибка)

Стандартный объект ошибки.