База знаний
Войти

Общая идеология API Cервиса

API РОСА ID использует только HTTPS-запросы, направляемые на домен, на котором разворачивается платформа Сервиса. В запросе всегда указывается путь к нужному URL в домене относительно "/api". Например, для домена id.rosa.ru нужно использовать – id.rosa.ru/api. Если в описании указан запрос auth/authorize, то его URL необходимо сформировать следующим образом: https://id.rosa.ru/api/auth/authorize.

Все запросы, требующие авторизации пользователя, должны передавать токен доступа в заголовке X-Lamb-Auth-Token. Для OAuth-запросов используется стандартный заголовок "Authorization: Bearer ". Предусмотрена следующая логика авторизации:

  1. пользователь регистрируется через /auth/register и подтверждает email через OTP-код;
  2. выполняет вход по email/паролю через /auth/authorize, получая access_token и refresh_token;
  3. при запросах к защищенным ресурсам передает access_token в заголовке X-Lamb-Auth-Token;
  4. для OAuth-клиентов используется стандартный поток authorization_code.

Все приложения, выполняющие авторизацию, запрос токенов или управление сеансами через Росa ID должны передавать корректно сформированную информацию в заголовке User-Agent (требования см. Приложение А).

Заголовок User-Agent передаётся в каждом HTTP-запросе к API Росa ID.

Информация заголовка User-Agent используется Сервисом для:

  • идентификации типа устройства (ПК, смартфон, сервер);
  • корректного отображения списка подключённых устройств в личном кабинете пользователя;
  • построения статистики по версиям ОС и приложений;
  • обнаружения аномалий и подозрительных сеансов.

Некорректное или отсутствующее значение может привести к невозможности отобразить устройство в разделе «Устройства»/«Сеансы».

Запросы с методом POST или PATCH обычно содержат тело запроса в формате JSON, поэтому в запросе обязательно должно быть указано поле заголовка:

 >Content-type: application/json

Тело запроса формируется как структура данных, содержащая перечисление параметров. Таким образом, если в описании конкретного запроса указаны параметры P1 и P2, то тело запроса должно быть сформировано как JSON следующего вида:

{"P1": value, "P2": value}

Все даты и время передаются в формате ISO 8601 в часовом поясе UTC. Unix-метки времени (TIME64) также поддерживаются в некоторых ответах, но в основном API использует ISO-строки для читаемости.

Пример: "2026-04-17T12:37:09Z".

Все методы, возвращающие коллекции, поддерживают пагинацию через параметры запроса offset и limit. Ответ с пагинацией содержит поля items, total_count, offset, limit.

Ответ сервера всегда приходит в формате JSON. В случае успеха возвращается HTTP-код 200 (или 204), а в теле — запрошенные данные.

В случае ошибки возвращается соответствующий HTTP-код (400, 401, 403, 404, 429, 500) и JSON-объект с полями error (символьный код ошибки) и message (описание ошибки) (см. Приложение Б).