Mobile ID Auth Lite API

Mobile ID — это сервис аутентификации пользователя по номеру мобильного телефона через SIM-push-уведомление. Он помогает подтвердить, что номер принадлежит пользователю и доступен ему в момент входа, регистрации или подтверждения действия.

SIM-push — это запрос на подтверждение, который отображается на устройстве пользователя без перехода в SMS. Пользователь подтверждает действие на экране телефона, а сервис возвращает результат аутентификации. Если SIM-push невозможно доставить, сценарий может перейти на SMS-код: пользователь получает код в SMS, вводит его на вашей площадке, а вы передаёте код в API для проверки.

Mobile ID Auth Lite API — это упрощённый способ подключить аутентификацию через SIM-push и каскад на SMS через единый API МТС KYC платформы. Сервис запускает аутентификацию в Mobile ID, обрабатывает промежуточные состояния и возвращает понятный статус сессии.

Как выглядит сценарий

1. Пользователь вводит номер телефона на вашей площадке.
2. Вы создаёте сессию аутентификации через Mobile ID Auth Lite API.
3. Пользователь получает SIM-push-уведомление и подтверждает действие на устройстве.
4. Если SIM-push недоступен, сервис запрашивает SMS-код.
5. Пользователь вводит SMS-код на вашей площадке, а вы передаёте его в API.
6. Вы получаете итоговый статус сессии и используете subId при успешной аутентификации.

Шаги интеграции

1. Получите client_id и client_secret.
2. Получите OAuth-токен для вызова API.
3. Создайте сессию аутентификации по номеру телефона.
4. Получайте состояние сессии через polling или callback.
5. Если требуется SMS-код, покажите пользователю форму ввода и передайте код в API.
6. Завершайте сценарий только после статуса success.

Перед началом

Для подключения нужны:

• client_id;
• client_secret;
• доступ к Mobile ID Auth Lite API;
• серверное хранилище для client_secret;
• callback URL, если результат нужно получать без постоянного опроса.

⚠️ Важно: client_secret должен храниться только на серверной стороне. Не передавайте его в браузер, мобильное приложение или публичные конфигурационные файлы.

Базовый адрес

Production base URL:

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

Все пути API добавляются к этому адресу.

Авторизация

API использует OAuth 2.0 с грантом client_credentials.

curl --location 'https://api.mts.ru/token' 
  --header 'Content-Type: application/x-www-form-urlencoded' 
  --header 'Authorization: Basic <base64(client_id:client_secret)>' 
  --data-urlencode 'grant_type=client_credentials'

В заголовке Authorization: Basic ... передаётся строка client_id:client_secret, закодированная в Base64.

Пример ответа токен-сервера:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "..."
}

Во всех запросах к API передавайте полученный токен:

Authorization: Bearer <access_token>

Кэшируйте access_token с учётом expires_in и обновляйте его до или после истечения срока действия.

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

Передайте номер пользователя и, при необходимости, свой идентификатор операции.

POST /api/v1/mobile-id-adapter/authentications
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "phoneNumber": "+79161234567",
  "externalId": "login-session-123"
}

Успешный ответ означает, что команда принята в обработку.

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. Он нужен для проверки состояния, передачи SMS-кода и сверки callback-ов.

ℹ️ Примечание: 202 Accepted не означает, что пользователь уже прошёл аутентификацию. Это только подтверждение, что сессия создана и обрабатывается.

2. Получайте состояние сессии

Запрашивайте состояние по authenticationId.

GET /api/v1/mobile-id-adapter/authentications/{authenticationId}
Authorization: Bearer <access_token>

Пример успешного результата:

{
  "authenticationId": "0195fa8e-61e5-7c40-b4af-f577674fd349",
  "externalId": "login-session-123",
  "status": "success",
  "createdAt": "2026-09-11T13:15:00Z",
  "updatedAt": "2026-09-11T13:15:48Z",
  "expiresAt": "2026-09-11T13:17:20Z",
  "smsCodeExpiresAt": null,
  "remainingAttempts": null,
  "subId": "873d1a98-23ef-42be-a14c-f577674fd349",
  "errorCode": null
}

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

3. Передайте SMS-код, если он нужен

Вызывайте метод только при статусе smsCodeRequired и до наступления smsCodeExpiresAt.

POST /api/v1/mobile-id-adapter/authentications/{authenticationId}/sms-code
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "code": "0842"
}

code передаётся строкой, чтобы сохранить ведущие нули.

Успешный ответ:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "authenticationId": "0195fa8e-61e5-7c40-b4af-f577674fd349"
}

После ответа продолжайте получать состояние сессии. Возможные результаты:

• smsCodeSubmitted — код отправлен на проверку, ожидайте результат;
• smsCodeRequired вместе с errorCode: "sms_code_invalid" — код неверен, можно повторить ввод до истечения срока или исчерпания попыток;
• success, failed или expired — сценарий завершён.

Статусы аутентификации

success, failed и expired — конечные статусы. Они больше не изменяются.

Не считайте пользователя аутентифицированным при любом результате, кроме status: "success" с непустым subId.

Бизнес-коды ошибок

Бизнес-ошибка передаётся в поле errorCode состояния и не обязательно сопровождается ошибочным HTTP-кодом.

HTTP-ошибки

Ошибки HTTP возвращаются в формате application/problem+json.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Invalid request",
  "status": 400,
  "detail": "Phone number must be in E.164 format, for example +79161234567"
}

Для сетевых ошибок и 503 используйте повторные попытки с увеличивающейся задержкой. Не создавайте новую аутентификацию автоматически после неоднозначного сетевого сбоя: сначала попытайтесь получить состояние по уже сохранённому authenticationId, если он был получен.

Callback

Если для вашего подключения заранее настроен callback, сервис отправляет изменения состояния методом POST на согласованный HTTPS-адрес.

POST <callbackUrl>
Content-Type: application/json; charset=utf-8
<согласованные заголовки авторизации>

Тело callback:

{
  "eventId": "0195faa1-5a22-75b6-b4a7-06be89d82a0d",
  "occurredAt": "2026-09-11T13:15:48Z",
  "authentication": {
    "id": "0195fa8e-61e5-7c40-b4af-f577674fd349",
    "externalId": "login-session-123",
    "status": "success",
    "createdAt": "2026-09-11T13:15:00Z",
    "updatedAt": "2026-09-11T13:15:48Z",
    "expiresAt": "2026-09-11T13:17:20Z",
    "smsCodeExpiresAt": null,
    "remainingAttempts": null,
    "subId": "873d1a98-23ef-42be-a14c-f577674fd349",
    "errorCode": null
  }
}

Обработчик callback должен:

• принимать повторную доставку одного eventId идемпотентно;
• возвращать любой HTTP-код 2xx только после успешной обработки;
• не рассчитывать на порядок доставки разных событий;
• игнорировать изменение после уже обработанного конечного статуса;
• проверять согласованный заголовок авторизации callback.

Любой ответ вне диапазона 2xx, сетевой сбой или таймаут считаются неуспешной доставкой. При повторной доставке используется тот же eventId.

При наличии callback метод GET /api/v1/mobile-id-adapter/authentications/{authenticationId} всё равно остаётся источником актуального состояния и может использоваться для сверки.

Когда обращаться в поддержку

• API возвращает 403 Forbidden при корректном токене;
• устойчиво возвращается 503 Service Unavailable;
• в состоянии сессии пришёл errorCode: "tenant_configuration_error";