Вход через RS-ID (OAuth2)

1. Что такое вход через RS-ID

Вход через RS-ID позволяет пользователям входить на ваш сайт через мобильное приложение RS-ID вместо пароля. Интеграция построена по стандартному протоколу OAuth 2.0 Authorization Code.

Ваш сайт направляет пользователя на страницу авторизации RS-ID. На странице отображается QR-код; пользователь сканирует его в мобильном приложении RS-ID и подтверждает личность по лицу. Затем RS-ID возвращает пользователя на ваш сайт с одноразовым кодом авторизации, а ваш бэкенд обменивает этот код на подтверждённый профиль пользователя.

Вам не нужно работать с паролями, вводом паспортных данных или проверкой лица — это делает RS-ID, а ваш бэкенд получает подтверждённую личность.

Сценарии использования

Сценарий	Пример
Вход без пароля	Пользователи входят на ваш веб-портал, сканируя QR-код в приложении RS-ID.
Подтверждённая регистрация	Новый пользователь регистрируется в один шаг; аккаунт создаётся с подтверждёнными ФИО, ПИНФЛ и данными документа.
Вход в чувствительные сервисы	Банковские, страховые, государственные или медицинские порталы, где при каждом входе нужен реальный подтверждённый человек.
Единая личность для нескольких сервисов	Одна и та же личность RS-ID используется для входа в несколько ваших продуктов.

2. Терминология

Термин	Кто / что это
Клиент	Компания, которая интегрирует RS-ID (вы). Зарегистрирована в RS-ID как проект типа AUTH и получила `client_id` / `client_secret` и зарегистрированный `redirect_uri`. Включает фронтенд клиента (ваш сайт) и бэкенд клиента.
Пользователь	Человек, который входит, — ваш клиент, у которого есть мобильное приложение RS-ID.
Страница авторизации RS-ID	Веб-страница RS-ID, на которой пользователь сканирует QR-код.
Мобильное приложение RS-ID	Приложение RS-ID на телефоне пользователя, через которое он сканирует QR-код и подтверждает личность.
Сервер	Сервер RS-ID, который выдаёт коды авторизации и возвращает профиль пользователя.
Код авторизации (`code`)	Одноразовый код, который RS-ID отправляет на ваш `redirect_uri` после входа пользователя. Действует 5 минут, используется один раз.
`redirect_uri`	URL на вашем сайте, куда RS-ID возвращает пользователя с `code`. Должен быть зарегистрирован в RS-ID.
`state`	Случайное значение, которое ваш сайт генерирует для каждого входа и проверяет при возврате, — защита от CSRF.
ПИНФЛ	Персональный идентификационный номер физического лица — 14 цифр.

3. Как это работает

Пользователь нажимает Войти через RS-ID на вашем сайте.

Ваш сайт перенаправляет пользователя на страницу авторизации RS-ID с параметрами client_id, redirect_uri, response_type=code и state (7.1).

Страница авторизации показывает QR-код, который обновляется каждые 30 секунд (7.2).

Пользователь сканирует QR-код в мобильном приложении RS-ID и подтверждает личность.

Страница авторизации перенаправляет пользователя на ваш redirect_uri с code и state (7.3).

Ваш бэкенд проверяет state и обменивает code на профиль пользователя через POST /v1/user/by-code (7.4).

Вы выполняете вход пользователя в свою систему.

4. Схема интеграции

5. Окружения

Окружение	Страница авторизации RS-ID	Базовый URL API
Stage (тестовое)	`https://auth.stage.rsid.uz`	`https://sdk.stage.rsid.uz/web/api`
Production	`https://auth.rsid.uz`	`https://sdk.rsid.uz/web/api`

Для stage и production используются разные client_id / client_secret. redirect_uri регистрируется отдельно для каждого окружения.

6. Общие правила

Формат ответа

Все ответы API имеют одинаковую структуру:

{ "data": { }, "code": 0, "message": "Success" }

Поле	Тип	Описание
`code`	integer	`0` — успех. Любое другое значение — ошибка (см. таблицы ошибок). Всегда проверяйте `code`, а не только HTTP-статус.
`message`	string	Текст на языке запроса (uz / ru / en). Не разбирайте его программно.
`data`	any	Данные ответа. Отсутствует при ошибке.

Безопасность

client_secret хранится только на вашем бэкенде. Никогда не передавайте его в браузер или мобильное приложение. Обменивайте code только с бэкенда.

Всегда используйте и проверяйте state. Генерируйте новый случайный state для каждого входа, сохраняйте его в сессии пользователя и отклоняйте возврат, если значение не совпадает.

Код одноразовый и короткоживущий. Обменивайте его сразу — он действует 5 минут и используется только один раз.

Используйте HTTPS для redirect_uri.

7. Описание API

7.1 Перенаправление пользователя на страницу авторизации RS-ID

Ваш сайт направляет браузер пользователя на страницу авторизации RS-ID.

Метод - GET (перенаправление браузера)
URL - {auth_page_url}/

Query-параметры

Поле	Тип	Обязательно	Длина / формат	Описание
`client_id`	string	Да	—	Ваш `client_id`, выданный RS-ID.
`redirect_uri`	string	Да	URL, в URL-кодировке	Куда RS-ID вернёт пользователя. Должен точно совпадать с `redirect_uri`, зарегистрированным в RS-ID.
`response_type`	string	Да	`code`	Всегда `code` (authorization code flow).
`state`	string	Рекомендуется	Случайная строка	Случайное значение, сгенерированное вашим сайтом для этого входа. Возвращается без изменений вместе с кодом.

Пример

https://auth.rsid.uz/?client_id=shop-example-auth&redirect_uri=https%3A%2F%2Fshop.example.uz%2Fauth%2Frsid%2Fcallback&response_type=code&state=Zx81kQ2mP0

7.2 Действия пользователя на странице авторизации RS-ID

Страница авторизации показывает QR-код. В целях безопасности QR-код генерируется заново каждые 30 секунд — старый QR-код использовать нельзя.

Пользователь открывает мобильное приложение RS-ID и сканирует QR-код.

Пользователь подтверждает личность в приложении (проверка по лицу).

После успешной идентификации страница авторизации возвращает пользователя на ваш сайт (7.3).

Если пользователь закрыл страницу или не успел отсканировать код, на ваш сайт ничего не отправляется; пользователь может начать заново с 7.1.

7.3 Возврат на ваш сайт с кодом

После успешного входа страница авторизации RS-ID перенаправляет браузер пользователя на ваш redirect_uri:

https://shop.example.uz/auth/rsid/callback?code=Zx81kQ2mP0aB7cD9eF1gH3&state=Zx81kQ2mP0

Параметр	Описание
`code`	Одноразовый код авторизации. Действует 5 минут, используется один раз.
`state`	Значение, которое вы отправили в 7.1. Сравните его с сохранённым в сессии пользователя; если не совпадает — прервите вход.

Ваша callback-страница передаёт code (и state) вашему бэкенду, который вызывает 7.4.

7.4 Получение данных пользователя по коду

Бэкенд клиента обменивает код авторизации на подтверждённый профиль пользователя.

Метод - POST
Endpoint - {base_url}/v1/user/by-code — без заголовка Authorization
Content-Type (заголовок) - application/json

Тело запроса

Поле	Тип	Обязательно	Длина / формат	Описание
`client_id`	string	Да	Не пустое	Ваш `client_id` (проект AUTH).
`client_secret`	string	Да	Не пустое	Ваш `client_secret`.
`code`	string	Да	Не пустое	`code` из 7.3.
`grant_type`	string	Да	`authorization_code`	Всегда `authorization_code`.

{
  "client_id": "shop-example-auth",
  "client_secret": "s3cr3t-value",
  "code": "Zx81kQ2mP0aB7cD9eF1gH3",
  "grant_type": "authorization_code"
}

Ответ

Поле	Тип	Описание
`data.user_info.first_name`	string	Имя.
`data.user_info.last_name`	string	Фамилия.
`data.user_info.middle_name`	string	Отчество. `-`, если его нет.
`data.user_info.pinfl`	string	ПИНФЛ, 14 цифр. Используйте его как постоянный идентификатор пользователя.
`data.user_info.gender`	string	Пол.
`data.user_info.birth_date`	string	`yyyy-MM-dd`.
`data.user_info.birth_place`	string	Место рождения.
`data.document_info.document`	string	Серия и номер документа.
`data.document_info.type`	string	Тип документа.
`data.document_info.issued_by`	string	Кем выдан.
`data.document_info.issued_at`	string	Дата выдачи, `yyyy-MM-dd`.
`data.document_info.expiry_at`	string	Срок действия, `yyyy-MM-dd`.
`data.contact_info.phone`	string	Номер телефона из аккаунта RS-ID.
`data.contact_info.email`	string	Email из аккаунта RS-ID, если указан.
`data.permanent_address`	object	В этом сценарии не возвращается (`null`).
`data.temporary_address`	object	В этом сценарии не возвращается (`null`).
`code`	integer	`0` при успехе.
`message`	string	Текст результата.

{
  "data": {
    "user_info": {
      "first_name": "ALISHER",
      "last_name": "KARIMOV",
      "middle_name": "BAXTIYOROVICH",
      "pinfl": "12345678901234",
      "gender": "MALE",
      "birth_date": "1990-01-01",
      "birth_place": "TOSHKENT",
      "birth_country": null,
      "nationality": null,
      "citizenship": null
    },
    "document_info": {
      "document": "AA1234567",
      "type": "PASSPORT",
      "issued_by": "IIV 26283",
      "issued_at": "2018-05-10",
      "expiry_at": "2028-05-09"
    },
    "contact_info": {
      "phone": "998901234567",
      "email": "alisher.karimov@example.uz"
    },
    "permanent_address": null,
    "temporary_address": null
  },
  "code": 0,
  "message": "Success"
}

Ошибки

Код	Причина
`-1083`	`client_id` не найден.
`-1002`	Клиент не является проектом AUTH.
`-1089`	`grant_type` не равен `authorization_code`.
`-1018`	`code` недействителен, истёк (старше 5 минут) или уже использован, либо неверный `client_secret`. Начните вход заново с 7.1.
`-1035`	`code` не связан со входом. Начните вход заново с 7.1.
`400`	Не заполнено обязательное поле.

8. Коды ошибок

Код	Название	Значение
`0`	SUCCESS	Успех.
`-9`	SYSTEM_ERROR	Непредвиденная ошибка сервера.
`-1002`	CLIENT_NOT_PERMITTED	Клиент не является проектом AUTH.
`-1018`	USER_NOT_FOUND	Код недействителен, истёк или уже использован, либо неверные учётные данные.
`-1035`	INVALID_QR_TOKEN	Код не связан со входом.
`-1083`	CLIENT_PROJECT_NOT_FOUND	`client_id` не найден.
`-1089`	INVALID_GRAND_TYPE	`grant_type` не равен `authorization_code`.

Вход через RS-ID (OAuth2)

1. Что такое вход через RS-ID#

Сценарии использования#

2. Терминология#

3. Как это работает#

4. Схема интеграции#

5. Окружения#

6. Общие правила#

Формат ответа#

Безопасность#

7. Описание API#

7.1 Перенаправление пользователя на страницу авторизации RS-ID#

7.2 Действия пользователя на странице авторизации RS-ID#

7.3 Возврат на ваш сайт с кодом#

7.4 Получение данных пользователя по коду#

8. Коды ошибок#