KYC ПЛАТФОРМА

Аутентификация через Mobile ID Auth LiteAPI

Mobile ID Auth LiteAPI позволяет подтвердить доступность и владение номером телефона через SIM-push. Если SIM-push недоступен, сценарий может перейти на проверку SMS-кодом.

Особенности подключения / интеграции

  • Для интеграции используется отдельный REST API LiteAPI и OAuth 2.0 с грантом client_credentials
  • LiteAPI поддерживает только SIM-push и SMS-код как резервный способ подтверждения
  • Результат можно получать запросом состояния (polling) или callback-ом, если он заранее настроен для подключения
  • client_secret используется только на сервере сервис-провайдера

Как выглядит процесс для пользователя?

  1. На площадке сервис-провайдера пользователь вводит номер телефона
  2. Пользователь подтверждает запрос в SIM-push на своём устройстве
  3. Если SIM-push недоступен, пользователь получает SMS и вводит код на площадке сервис-провайдера
  4. После успешной проверки сервис-провайдер продолжает пользовательский сценарий

Как выглядит процесс для сервис-провайдера?

1. Получите токен доступа

Production base URL LiteAPI:

https://api.mts.ru/Id-Kyc-MobileIdAdapter-Prod/1.0

Запросите access token с грантом client_credentials:

POST https://api.mts.ru/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=client_credentials

Во всех запросах LiteAPI передавайте токен в заголовке:

Authorization: Bearer <access_token>

2. Создайте сессию аутентификации

Передайте номер пользователя. externalId — необязательный идентификатор операции на стороне сервис-провайдера.

POST https://api.mts.ru/Id-Kyc-MobileIdAdapter-Prod/1.0/api/v1/mobile-id-adapter/authentications
Content-Type: application/json
Authorization: Bearer <access_token>
{
  "phoneNumber": "+79161234567",
  "externalId": "login-session-123"
}

Номер передаётся в формате +7XXXXXXXXXX. Пример ответа:

HTTP/1.1 202 Accepted
Content-Type: application/json
{
  "authenticationId": "0195fa8e-61e5-7c40-b4af-f577674fd349",
  "status": "pending",
  "expiresAt": "2026-09-11T13:17:20Z",
  "errorCode": null
}

Сохраните authenticationId. Ответ 202 Accepted означает, что операция принята в обработку, а не что пользователь уже аутентифицирован.

3. Дождитесь подтверждения пользователя

Mobile ID запускает SIM-push. Проверяйте состояние сессии:

GET https://api.mts.ru/Id-Kyc-MobileIdAdapter-Prod/1.0/api/v1/mobile-id-adapter/authentications/{authenticationId}
Authorization: Bearer <access_token>

Пример промежуточного состояния:

{
  "authenticationId": "0195fa8e-61e5-7c40-b4af-f577674fd349",
  "externalId": "login-session-123",
  "status": "pending",
  "createdAt": "2026-09-11T13:15:00Z",
  "updatedAt": "2026-09-11T13:15:00Z",
  "expiresAt": "2026-09-11T13:17:20Z",
  "smsCodeExpiresAt": null,
  "remainingAttempts": null,
  "subId": null,
  "errorCode": null
}

Рекомендуемый интервал polling — не чаще одного запроса в две секунды.

4. Если требуется SMS-код, передайте его в LiteAPI

Если в состоянии сессии пришёл статус smsCodeRequired, покажите пользователю форму ввода SMS-кода. Передайте код до наступления smsCodeExpiresAt:

POST https://api.mts.ru/Id-Kyc-MobileIdAdapter-Prod/1.0/api/v1/mobile-id-adapter/authentications/{authenticationId}/sms-code
Content-Type: application/json
Authorization: Bearer <access_token>
{
  "code": "0842"
}

code передаётся строкой из 3–10 цифр, чтобы не потерять ведущие нули. Успешный запрос возвращает 202 Accepted; продолжайте получать состояние сессии. При errorCode: "sms_code_invalid" повторный ввод возможен, пока не истёк срок кода и остались попытки.

5. Получите результат и завершите сценарий

Сессия может иметь статусы pending, smsCodeRequired, smsCodeSubmitted, success, failed или expired. Продолжайте polling либо принимайте callback, если он настроен для подключения.

При успешной аутентификации ответ содержит status: "success" и subId:

{
  "authenticationId": "0195fa8e-61e5-7c40-b4af-f577674fd349",
  "status": "success",
  "subId": "873d1a98-23ef-42be-a14c-f577674fd349",
  "errorCode": null
}

Сервис-провайдер должен считать пользователя аутентифицированным только при статусе success и непустом subId. Для failed обработайте errorCode; при expired можно создать новую сессию, если это уместно для пользовательского сценария.

Если используется callback, обработчик должен принимать повторную доставку одного eventId идемпотентно. GET состояния можно использовать для сверки актуального результата.

Подробности методов, статусов и ошибок: API Reference → Mobile ID API и Mobile ID Auth LiteAPI.