Восстановление доступа

Восстановить доступ

POST /(company_code)/v2/auth/recovery/recover

Восстановить доступ пользователя

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

Для клиентского приложения могут быть разрешены один или более из следующих методов восстановления:

PHONE
У пользователя должен быть установлен основной номер телефона. На этот телефон высылается одноразовый код. Возвращается временный сессионный токен с состоянием сессии recovery-checkotp. Клиенту следует далее использовать вызов API auth/recovery/checkotp, используя этот временный сессионный токен. Поле ответа verification будет содержать PHONE, а поле ответа user_phone маскированный номер телефона пользователя.
QUESTION
У пользователя должны быть контрольный вопрос и ответ. Возвращается временный сессионный токен с состоянием сессии recovery-checkquestion. Клиенту следует далее использовать вызов API auth/recovery/checkquestion, используя этот временный сессионный токен. Поле ответа verification будет содержать QUESTION, а поле ответа control_question текст контрольного вопроса пользователя.
MAIL
У пользователя должен быть установлен основной адрес электронной почты. На этот адрес высылается ссылка подтверждения. Сессионный токен не возвращается. Клиенту следует далее использовать вызов API auth/recovery/checklink, используя токен из ссылки подтверждения. Поле ответа verification будет содержать MAIL, а поле ответа user_email адрес электронной почты пользователя.

Если в запросе не передан желательный метод восстановления, выбирается метод по умолчанию. Если метод восстановления запрещен, возвращается код ошибки recovery.method.restricted со статусом HTTP 403.

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

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

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

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

JSON-объект запроса:
 
  • login_id (string) – Идентификатор для входа пользователя (основной телефон, основная электронная почта или отдельное имя для входа)
  • captcha_response (string) – Ответный токен captcha пользователя в виде, предоставленном Recaptcha
  • method (string) – (Необязательно) Желательный метод восстановления: PHONE, MAIL или QUESTION
JSON-объект ответа:
 
  • status (string) – success или error
  • error_code (string) – (Необязательно) Если status содержит error: один из перечисленных ниже кодов ошибки
  • verification (string) – Тип проверки (метод восстановления): PHONE, MAIL или QUESTION
  • session_token (string) – (Необязательно) Если verification содержит PHONE или QUESTION: Сессионный токен пользователя
  • session_state (string) – (Необязательно) Если verification содержит PHONE или QUESTION: Состояние сессии пользователя: recovery-checkotp или recovery-checkquestion. См. Пользовательские сессии
  • user_phone (string) – (Необязательно) Если verification содержит PHONE: Маскированный номер телефона пользователя
  • user_email (string) – (Необязательно) Если verification содержит MAIL: Адрес электронной почты пользователя
  • control_question (string) – (Необязательно) Если verification содержит QUESTION: Текст контрольного вопроса пользователя

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

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.loginid.notfound
  • auth.captcha.invalid
  • recovery.method.restricted
  • recovery.phone.notset
  • recovery.email.notset
  • recovery.question.notset
  • auth.user.restricted
  • auth.user.closed
  • auth.user.denied
  • request.validation.failed

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

Проверить OTP восстановления

POST /(company_code)/v2/auth/recovery/checkotp

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

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

По успешной проверке кода восстановления будет возвращен временный сессионный токен с состоянием сессии recovery-setpassword. Клиенту следует далее использовать вызов API auth/setpassword с полученным временным сессионным токеном.

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

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

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

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

Обновить OTP восстановления

POST /(company_code)/v2/auth/recovery/renewotp

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

Отправляет новый одноразовый код (OTP) на основной номер телефона пользователя.

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

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

  • 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/recovery/checkquestion

Проверить ответ на контрольный вопрос для восстановления доступа

При восстановлении доступа посредством контрольного вопроса API возвращает текст контрольного вопроса. Введенный пользователем текст ответа должен быть передан этому вызову. Если передан неверный ответ, возвращается код ошибки auth.controlanswer.invalid.

По успешной проверке контрольного ответа будет возвращен временный сессионный токен с состоянием сессии recovery-setpassword. Клиенту следует далее использовать вызов API auth/setpassword с полученным временным сессионным токеном.

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

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

  • auth.apikey.missing
  • auth.apikey.invalid
  • auth.header.missing
  • auth.header.invalid
  • auth.token.invalid
  • auth.token.expired
  • auth.session.invalid
  • auth.controlanswer.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

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