Вход пользователя

Схема процесса входа

Login Process Flow

Во время проверки пароля или OTP пользователь также должен принять соглашения, если это требуется. Отдельный вызов auth/acceptdisclaimers используется только при входе через OAuth.

Проверить идентификатор для входа

POST /(company_code)/v2/auth/login

Вход пользователя (проверка идентификатора для входа)

Проверяет идентификатор для входа пользователя (может быть основным телефоном, основной электронной почтой или отдельным именем для входа в зависимости от роли пользователя) и возвращает временный сессионный токен для дальнейшей аутентификации. Этот токен возвращается в поле ответа session_token и должен быть использован при обращении к соответствующим вызовам аутентификации.

Если профиль пользователя по указанному идентификатору для входа не найден, возвращает код ошибки auth.loginid.notfound со статусом HTTP 404.

Если авторизация пользователя по указанному идентификатору для входа запрещена, возвращает код ошибки auth.user.restricted со статусом HTTP 403.

Если профиль пользователя по указанному идентификатору для входа закрыт, возвращает код ошибки auth.user.closed со статусом HTTP 403.

Если для указанного идентификатора для входа в сервисе административно отказано, возвращает код ошибки auth.user.denied со статусом HTTP 403.

Если у профиля пользователя установлен пароль, поле ответа session_state будет содержать checkpassword. Клиентскому приложению следует далее использовать вызов auth/checkpassword, передавая полученный сессионный токен.

Если у профиля пользователя не установлен пароль, поле ответа session_state будет содержать checkotp. Клиентскому приложению следует далее использовать вызов auth/checkotp, передавая полученный сессионный токен и введенный пользователем одноразовый код (OTP).

Если пользователь должен принять юридические соглашения, массив ответа disclaimers_required будет содержать данные требуемых соглашений. Вызовы auth/checkpassword и auth/checkotp не будут выполнены успешно, если передаваемый список принятых соглашений не будет содержать коды всех требуемых соглашений.

JSON-объект запроса:
 
  • login_id (string) – Идентификатор для входа пользователя (основной телефон, основная электронная почта или отдельное имя для входа)
JSON-объект ответа:
 
  • status (string) – success или error
  • error_code (string) – (Необязательно) Если status содержит error: один из перечисленных ниже кодов ошибки
  • session_token (string) – Сессионный токен пользователя
  • session_state (string) – Состояние сессии пользователя: checkpassword или checkotp. См. Пользовательские сессии
  • disclaimers_required (array) – Массив объектов данных юридических соглашений, которые пользователь должен принять
  • captcha_required (boolean) – (Необязательно) Если session_state содержит checkpassword: true если у следующего запроса должно быть установлено поле captcha_response
  • user_phone (string) – (Необязательно) Если session_state содержит checkotp: маскированный номер телефона пользователя

Поля соглашений

Каждый член массива ответа disclaimers_required это объект со следующими полями:

Имя поля Тип Допускает null Описание
code string Нет Код соглашения
title string Нет Название соглашения для отображения
description string Нет Краткое описание соглашения
link string Нет URL ссылки на текст юридического соглашения

Используемые коды ошибки

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.loginid.notfound
  • auth.user.restricted
  • auth.user.closed
  • auth.user.denied
  • auth.restricted
  • request.validation.failed

Подробнее см. Коды ошибок.

Проверить пароль

POST /(company_code)/v2/auth/checkpassword

Проверить пароль пользователя для аутентификации

Если передан неверный пароль, возвращается код ошибки auth.password.invalid. Если было несколько предыдущих неудачных попыток, поле ответа captcha_required устанавливается в true. Дальнейшие запросы этого вызова должны включать поле captcha_response, содержащее правильный ответ Recaptcha.

Если пользователь должен принять юридические соглашения, для успешного выполнения этого вызова массив запроса accept_disclaimers должен содержать коды всех требуемых соглашений. Иначе возвращается код ошибки auth.disclaimer.invalid, а поле ответа disclaimers_required содержит массив требуемых соглашений.

Если требуется проверка второго фактора, будет возвращен временный сессионный токен с состоянием сессии checkotp. Далее клиенту следует использовать вызов API auth/checkotp с полученным временным сессионным токеном. Поле ответа user_phone будет содержать маскированный номер телефона для проверки SMS.

Если пользователь должен установить новый пароль, будет возвращен временный сессионный токен с состоянием сессии setpassword. Далее клиенту следует использовать вызов API auth/setpassword с полученным временным сессионным токеном.

Если никаких дальнейших действий по авторизации не требуется, у возвращаемого сессионного токена будет состояние сессии authorized. Поле ответа profile_mnemocode будет содержать мнемокод профиля пользователя для связанных с профилем вызовов API.

Заголовки запроса:
 
  • Authorization – Bearer <сессионный_токен> (состояние сессии должно быть checkpassword)
JSON-объект запроса:
 
  • password (string) – Введенный пользователем пароль
  • captcha_response (string) – (Необязательно) Ответный токен captcha пользователя в виде, предоставленном Recaptcha
  • accept_disclaimers (array) – (Необязательно) Массив строковых кодов соглашений, принятых пользователем
JSON-объект ответа:
 
  • status (string) – success или error
  • error_code (string) – (Необязательно) Если status содержит error: один из перечисленных ниже кодов ошибки
  • captcha_required (boolean) – (Необязательно) Если status содержит error: true если у следующего запроса должно быть установлено поле captcha_response
  • disclaimers_required (array) – (Необязательно) Если status содержит error: Массив объектов данных юридических соглашений, которые нужно принять пользователю
  • session_token (string) – Сессионный токен пользователя
  • session_state (string) – Состояние сессии пользователя: checkotp, setpassword или authorized. См. Пользовательские сессии
  • profile_mnemocode (string) – (Необязательно) Если session_state содержит authorized: Мнемокод профиля пользователя
  • user_phone (string) – (Необязательно) Если session_state содержит checkotp: маскированный номер телефона пользователя
  • password_regex (string/null) – (Необязательно) Если session_state содержит setpassword: Регулярное выражение для проверки качества пароля (проверка отключена, если null)
  • password_regex_description (string/null) – (Необязательно) Если session_state содержит setpassword: Текст описания для проверки качества пароля

Поля соглашений

Каждый член массива ответа disclaimers_required это объект со следующими полями:

Имя поля Тип Допускает null Описание
code string Нет Код соглашения
title string Нет Название соглашения для отображения
description string Нет Краткое описание соглашения
link string Нет URL ссылки на текст юридического соглашения

Используемые коды ошибки

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.header.missing
  • auth.header.invalid
  • auth.token.invalid
  • auth.token.expired
  • auth.session.invalid
  • auth.user.restricted
  • auth.user.closed
  • auth.user.denied
  • auth.captcha.missing
  • auth.captcha.invalid
  • auth.password.invalid
  • auth.disclaimer.invalid
  • auth.restricted
  • request.validation.failed

Подробнее см. Коды ошибок.

Проверить OTP

POST /(company_code)/v2/auth/checkotp

Проверить одноразовый код для аутентификации

При аутентификации с OTP на основной номер телефона пользователя высылается одноразовый код (OTP). Ответ API включает поле user_phone, содержащее маскированный номер телефона пользователя. Введенный пользователем код должен быть передан этому вызову в поле запроса otp. Если передан неверный код, возвращается код ошибки auth.otp.invalid. Перед повторной попыткой этого вызова нужно использовать вызов auth/renewotp для отправки нового кода.

Если у пользователя нет доступа к телефону, они могут выбрать использовать вместо кода из SMS заранее сгенерированный резервный код. Этот код должен быть передан в поле запроса backup_code. Если передан неверный код, возвращается код ошибки auth.backupcode.invalid.

Если пользователь должен принять юридические соглашения, для успешного выполнения этого вызова массив запроса accept_disclaimers должен содержать коды всех требуемых соглашений. Иначе возвращается код ошибки auth.disclaimer.invalid, а поле ответа disclaimers_required содержит массив требуемых соглашений. Перед повторной попыткой этого вызова нужно использовать вызов auth/renewotp для отправки нового одноразового кода.

Если пользователь должен установить новый пароль, будет возвращен временный сессионный токен с состоянием сессии setpassword. Далее клиенту следует использовать вызов API auth/setpassword с полученным временным сессионным токеном.

Если никаких дальнейших действий по авторизации не требуется, у возвращаемого сессионного токена будет состояние сессии authorized. Поле ответа profile_mnemocode будет содержать мнемокод профиля пользователя для связанных с профилем вызовов API.

Заголовки запроса:
 
  • Authorization – Bearer <сессионный_токен> (состояние сессии должно быть checkotp)
JSON-объект запроса:
 
  • otp (string) – (Необязательно) Введенный пользователем одноразовый код из SMS
  • backup_code (string) – (Необязательно) Введенный пользователем резервный код
  • accept_disclaimers (array) – (Необязательно) Массив строковых кодов соглашений, принятых пользователем
JSON-объект ответа:
 
  • status (string) – success или error
  • error_code (string) – (Необязательно) Если status содержит error: один из перечисленных ниже кодов ошибки
  • disclaimers_required (array) – (Необязательно) Если status содержит error: Массив объектов данных юридических соглашений, которые нужно принять пользователю
  • session_token (string) – Сессионный токен пользователя
  • session_state (string) – Состояние сессии пользователя: setpassword или authorized. См. Пользовательские сессии
  • profile_mnemocode (string) – (Необязательно) Если session_state содержит authorized: Мнемокод профиля пользователя
  • password_regex (string/null) – (Необязательно) Если session_state содержит setpassword: Регулярное выражение для проверки качества пароля (проверка отключена, если null)
  • password_regex_description (string/null) – (Необязательно) Если session_state содержит setpassword: Текст описания для проверки качества пароля

Поля соглашений

Каждый член массива ответа disclaimers_required это объект со следующими полями:

Имя поля Тип Допускает null Описание
code string Нет Код соглашения
title string Нет Название соглашения для отображения
description string Нет Краткое описание соглашения
link string Нет URL ссылки на текст юридического соглашения

Используемые коды ошибки

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.header.missing
  • auth.header.invalid
  • auth.token.invalid
  • auth.token.expired
  • auth.session.invalid
  • auth.user.restricted
  • auth.user.closed
  • auth.user.denied
  • auth.otp.invalid
  • auth.backupcode.invalid
  • auth.disclaimer.invalid
  • auth.restricted
  • request.validation.failed

Подробнее см. Коды ошибок.

Обновить OTP

POST /(company_code)/v2/auth/renewotp

Обновить одноразовый код для аутентификации

На основной номер телефона пользователя высылается новый одноразовый код (OTP). Поле ответа user_phone содержит маскированный номер телефона пользователя.

Заголовки запроса:
 
  • Authorization – Bearer <сессионный_токен> (состояние сессии должно быть checkotp)
JSON-объект ответа:
 
  • status (string) – success или error
  • error_code (string) – (Необязательно) Если status содержит error: один из перечисленных ниже кодов ошибки
  • user_phone (string) – Маскированный номер телефона пользователя

Используемые коды ошибки

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.header.missing
  • auth.header.invalid
  • auth.token.invalid
  • auth.token.expired
  • auth.session.invalid
  • auth.user.restricted
  • auth.user.closed
  • auth.user.denied
  • request.validation.failed

Подробнее см. Коды ошибок.

Установить пароль

POST /(company_code)/v2/auth/setpassword

Установить или изменить пароль пользователя

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

При использовании в процессе авторизации (состояние сессии setpassword), будет возвращен новый сессионный токен со состоянием сессии authorized. Поле ответа profile_mnemocode будет содержать мнемокод профиля пользователя.

При использовании в процессе восстановления доступа (состояние сессии recovery-setpassword), новый сессионный токен возвращен не будет. Клиентскому приложению следует далее использовать вызов auth/login для авторизации пользователя с восстановленным доступом.

Если качество переданного нового пароля слишком низкое, возвращает код ошибки request.validation.failed со статусом HTTP 422.

Заголовки запроса:
 
  • Authorization – Bearer <сессионный_токен> (состояние сессии должно быть setpassword или recovery-setpassword)
JSON-объект запроса:
 
  • new_password (string) – Новый пароль пользователя
JSON-объект ответа:
 
  • status (string) – success или error
  • error_code (string) – (Необязательно) Если status содержит error: один из перечисленных ниже кодов ошибки
  • session_token (string) – (Необязательно) Если session_state содержало setpassword: Сессионный токен пользователя
  • session_state (string) – (Необязательно) Если session_state содержало setpassword: Состояние сессии пользователя: authorized. См. Пользовательские сессии
  • profile_mnemocode (string) – (Необязательно) Если session_state содержало setpassword: Мнемокод профиля пользователя

Используемые коды ошибки

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.header.missing
  • auth.header.invalid
  • auth.token.invalid
  • auth.token.expired
  • auth.session.invalid
  • auth.password.invalid
  • auth.user.restricted
  • auth.user.closed
  • auth.user.denied
  • request.validation.failed

Подробнее см. Коды ошибок.

Check Credentials

POST /(company_code)/v2/auth/checkcredentials

Check user credentials for authentication

Verifies user login ID (can be primary phone, primary email, or a separate login name depending on user role) and password for user authentication.

If invalid login_id or password was supplied, auth.credentials.invalid error code is returned. If there were several previous failed attempts, captcha_required response field is set to true. Further requests to this endpoint must include captcha_response field containing valid Recapthca response.

Если пользователь должен принять юридические соглашения, для успешного выполнения этого вызова массив запроса accept_disclaimers должен содержать коды всех требуемых соглашений. Иначе возвращается код ошибки auth.disclaimer.invalid, а поле ответа disclaimers_required содержит массив требуемых соглашений.

Если требуется проверка второго фактора, будет возвращен временный сессионный токен с состоянием сессии checkotp. Далее клиенту следует использовать вызов API auth/checkotp с полученным временным сессионным токеном. Поле ответа user_phone будет содержать маскированный номер телефона для проверки SMS.

Если пользователь должен установить новый пароль, будет возвращен временный сессионный токен с состоянием сессии setpassword. Далее клиенту следует использовать вызов API auth/setpassword с полученным временным сессионным токеном.

Если никаких дальнейших действий по авторизации не требуется, у возвращаемого сессионного токена будет состояние сессии authorized. Поле ответа profile_mnemocode будет содержать мнемокод профиля пользователя для связанных с профилем вызовов API.

Если авторизация пользователя по указанному идентификатору для входа запрещена, возвращает код ошибки auth.user.restricted со статусом HTTP 403.

Если профиль пользователя по указанному идентификатору для входа закрыт, возвращает код ошибки auth.user.closed со статусом HTTP 403.

Если для указанного идентификатора для входа в сервисе административно отказано, возвращает код ошибки auth.user.denied со статусом HTTP 403.

JSON-объект запроса:
 
  • login_id (string) – Идентификатор для входа пользователя (основной телефон, основная электронная почта или отдельное имя для входа)
  • password (string) – Введенный пользователем пароль
  • captcha_response (string) – (Необязательно) Ответный токен captcha пользователя в виде, предоставленном Recaptcha
  • accept_disclaimers (array) – (Необязательно) Массив строковых кодов соглашений, принятых пользователем
JSON-объект ответа:
 
  • status (string) – success или error
  • error_code (string) – (Необязательно) Если status содержит error: один из перечисленных ниже кодов ошибки
  • captcha_required (boolean) – (Необязательно) Если status содержит error: true если у следующего запроса должно быть установлено поле captcha_response
  • disclaimers_required (array) – (Необязательно) Если status содержит error: Массив объектов данных юридических соглашений, которые нужно принять пользователю
  • session_token (string) – Сессионный токен пользователя
  • session_state (string) – Состояние сессии пользователя: checkotp, setpassword или authorized. См. Пользовательские сессии
  • profile_mnemocode (string) – (Необязательно) Если session_state содержит authorized: Мнемокод профиля пользователя
  • user_phone (string) – (Необязательно) Если session_state содержит checkotp: маскированный номер телефона пользователя
  • password_regex (string/null) – (Необязательно) Если session_state содержит setpassword: Регулярное выражение для проверки качества пароля (проверка отключена, если null)
  • password_regex_description (string/null) – (Необязательно) Если session_state содержит setpassword: Текст описания для проверки качества пароля

Поля соглашений

Каждый член массива ответа disclaimers_required это объект со следующими полями:

Имя поля Тип Допускает null Описание
code string Нет Код соглашения
title string Нет Название соглашения для отображения
description string Нет Краткое описание соглашения
link string Нет URL ссылки на текст юридического соглашения

Используемые коды ошибки

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.captcha.missing
  • auth.captcha.invalid
  • auth.credentials.invalid
  • auth.disclaimer.invalid
  • auth.user.restricted
  • auth.user.closed
  • auth.user.denied
  • auth.restricted
  • request.validation.failed

Подробнее см. Коды ошибок.

Вход через OAuth

POST /(company_code)/v2/auth/oauth

Аутентифицировать пользователя в провайдере OAuth

Проверяет код авторизации OAuth в одном из сконфигурированных провайдеров OAuth и возвращает сессионный токен пользователя.

Если проверка в провайдере OAuth не удалась, возможно из-за неверных значений code или redirect_uri, возвращает код ошибки auth.oauth.failed со статусом HTTP 401.

Если профиль пользователя для проверенного пользователя провайдера OAuth не найден, возвращает код ошибки auth.oauth.notfound со статусом HTTP 404.

Если авторизация пользователя для аутентифицированного в провайдере OAuth пользователя запрещена, возвращает код ошибки auth.user.restricted со статусом HTTP 403.

Если профиль пользователя для аутентифицированного в провайдере OAuth пользователя закрыт, возвращает код ошибки auth.user.closed со статусом HTTP 403.

Если аутентифицированному в провайдере OAuth пользователю в сервисе административно отказано, возвращает код ошибки auth.user.denied со статусом HTTP 403.

Если пользователь должен принять юридические соглашения, поле ответа session_state будет содержать acceptdisclaimers, а массив ответа disclaimers_required будет содержать данные требуемых соглашений. Клиентскому приложению следует далее использовать вызов auth/acceptdisclaimers, передавая полученный сессионный токен и список принятых соглашений.

Если пользователю не нужно принимать юридические соглашения, у возвращаемого сессионного токена будет состояние сессии authorized. Поле ответа profile_mnemocode будет содержать мнемокод профиля пользователя для связанных с профилем вызовов API.

JSON-объект запроса:
 
  • provider_id (integer) – Идентификатор провайдера OAuth, должен быть от 1 до 5
  • code (string) – Код OAuth в виде, полученном от провайдера OAuth
  • redirect_uri (string) – URI перенаправления в виде, переданном провайдеру OAuth
JSON-объект ответа:
 
  • status (string) – success или error
  • error_code (string) – (Необязательно) Если status содержит error: один из перечисленных ниже кодов ошибки
  • session_token (string) – Сессионный токен пользователя
  • session_state (string) – Состояние сессии пользователя: authorized или acceptdisclaimers. См. Пользовательские сессии
  • disclaimers_required (array) – (Необязательно) Если session_state содержит acceptdisclaimers: Массив объектов данных юридических соглашений, которые нужно принять пользователю
  • profile_mnemocode (string) – (Необязательно) Если session_state содержит authorized: Мнемокод профиля пользователя

Поля соглашений

Каждый член массива ответа disclaimers_required это объект со следующими полями:

Имя поля Тип Допускает null Описание
code string Нет Код соглашения
title string Нет Название соглашения для отображения
description string Нет Краткое описание соглашения
link string Нет URL ссылки на текст юридического соглашения

Используемые коды ошибки

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.header.missing
  • auth.header.invalid
  • auth.token.invalid
  • auth.token.expired
  • auth.session.invalid
  • auth.oauth.notfound
  • auth.oauth.failed
  • request.validation.failed
  • auth.user.restricted
  • auth.user.closed
  • auth.user.denied

Подробнее см. Коды ошибок.

Принять соглашения

POST /(company_code)/v2/auth/acceptdisclaimers

Принять юридические соглашения при авторизации

Возвращает сессионный токен с состоянием сессии authorized. Поле ответа profile_mnemocode будет содержать мнемокод профиля пользователя для связанных с профилем вызовов API.

Для успешного выполнения этого вызова массив запроса accept_disclaimers должен содержать коды всех требуемых соглашений. Иначе возвращается код ошибки auth.disclaimer.invalid, а поле ответа disclaimers_required содержит массив требуемых соглашений.

Заголовки запроса:
 
  • Authorization – Bearer <сессионный_токен> (состояние сессии должно быть acceptdisclaimers)
JSON-объект запроса:
 
  • accept_disclaimers (array) – (Необязательно) Массив строковых кодов соглашений, принятых пользователем
JSON-объект ответа:
 
  • status (string) – success или error
  • error_code (string) – (Необязательно) Если status содержит error: один из перечисленных ниже кодов ошибки
  • disclaimers_required (array) – (Необязательно) Если status содержит error: Массив объектов данных юридических соглашений, которые нужно принять пользователю
  • session_token (string) – Сессионный токен пользователя
  • session_state (string) – Состояние сессии пользователя: authorized. См. Пользовательские сессии
  • profile_mnemocode (string) – Мнемокод профиля пользователя

Поля соглашений

Каждый член массива ответа disclaimers_required это объект со следующими полями:

Имя поля Тип Допускает null Описание
code string Нет Код соглашения
title string Нет Название соглашения для отображения
description string Нет Краткое описание соглашения
link string Нет URL ссылки на текст юридического соглашения

Используемые коды ошибки

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.header.missing
  • auth.header.invalid
  • auth.token.invalid
  • auth.token.expired
  • auth.session.invalid
  • auth.user.restricted
  • auth.user.closed
  • auth.user.denied
  • auth.disclaimer.invalid
  • auth.restricted
  • request.validation.failed

Подробнее см. Коды ошибок.

Log Out

POST /(company_code)/v2/auth/logout

User logout (invalidate auth token)

Заголовки запроса:
 
JSON-объект ответа:
 
  • status (string) – success или error
  • error_code (string) – (Необязательно) Если status содержит error: один из перечисленных ниже кодов ошибки

Используемые коды ошибки

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.token.invalid
  • auth.token.expired
  • auth.session.invalid

Подробнее см. Коды ошибок.