Access Recovery

Recover Access

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

Recover user access

Verifies user login ID (can be primary phone, primary email, or a separate login name depending on user role) and captcha response for access recovery.

One or more of the following recovery methods may be allowed for a client application:

PHONE
User must have primary phone set. An SMS with one-time password (code) is sent to this phone. A temporary session token with recovery-checkotp session state is returned. Client is expected to call auth/recovery/checkotp API endpoint next using this temporary session token. verification response field is set to PHONE, user_phone response field is set to masked user’s phone number.
QUESTION
User must have control question and answer. A temporary session token with recovery-checkquestion session state is returned. Client is expected to call auth/recovery/checkquestion API endpoint next using this temporary session token. verification response field is set to QUESTION, control_question response field is set to the text of user’s control question.
MAIL
User must have primary email set. A message with confirmation link is sent to this email. No session token is returned. Client is expected to call auth/recovery/checklink API endpoint next supplying the token from confirmation link. verification response field is set to MAIL, user_email response field is set to user’s email address.

If no desired recovery method is supplied in request, a default method is chosen. If recovery method is restricted, recovery.method.restricted error code is returned with HTTP status code 403.

If user profile for supplied login ID is not found, auth.loginid.notfound error code is returned with HTTP status code 404.

If user authorization for supplied login ID is restricted, returns auth.user.restricted error code with HTTP status code 403.

If user profile for supplied login ID is closed, returns auth.user.closed error code with HTTP status code 403.

If service is administratively denied for supplied login ID, returns auth.user.denied error code with HTTP status code 403.

Request JSON Object:
 
  • login_id (string) – User login ID (primary phone, primary email, or a separate login name)
  • captcha_response (string) – User captcha response token, as provided by Recaptcha
  • method (string) – (Optional) Desired recovery method: PHONE, MAIL, or QUESTION
Response JSON Object:
 
  • status (string) – success or error
  • error_code (string) – (Optional) If status is error: one of error codes listed below
  • verification (string) – Type of verification (recovery method): PHONE, MAIL, or QUESTION
  • session_token (string) – (Optional) If verification is PHONE or QUESTION: User session token
  • session_state (string) – (Optional) If verification is PHONE or QUESTION: User session state: recovery-checkotp or recovery-checkquestion. See User Sessions
  • user_phone (string) – (Optional) If verification is PHONE: masked user’s phone number
  • user_email (string) – (Optional) If verification is MAIL: user’s email address
  • control_question (string) – (Optional) If verification is QUESTION: text of user’s control question

Error codes used

  • 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

See Error Codes for details.

Check Recovery OTP

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

Check one-time password for access recovery

When recovering access using phone method, user is send an SMS with one-time password. OTP entered by user must be supplied to this endpoint. If invalid OTP is supplied, auth.otp.invalid error code is returned. auth/recovery/renewotp endpoint must be used to send a new OTP before retrying this endpoint.

On successful validation of recovery OTP, a temporary session token with recovery-setpassword session state is returned. Client is expected to call auth/setpassword API endpoint next using this temporary session token.

Request Headers:
 
  • Authorization – Bearer <session_token> (session state must be recovery-checkotp)
Request JSON Object:
 
  • otp (string) – SMS one-time password entered by user
Response JSON Object:
 
  • status (string) – success or error
  • error_code (string) – (Optional) If status is error: one of error codes listed below
  • session_token (string) – User session token
  • session_state (string) – User session state: recovery-setpassword. See User Sessions
  • password_regex (string/null) – Regex to check required password quality (check disabled if null)
  • password_regex_description (string/null) – Description text for password quality check

Error codes used

  • 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

See Error Codes for details.

Renew Recovery OTP

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

Renew one-time password for access recovery

Sends a new one-time password (code) to user’s primary phone number.

Request Headers:
 
  • Authorization – Bearer <session_token> (session state must be recovery-checkotp)
Response JSON Object:
 
  • status (string) – success or error
  • error_code (string) – (Optional) If status is error: one of error codes listed below

Error codes used

  • 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

See Error Codes for details.

Check Control Question

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

Check answer to control question for access recovery

When recovering access using control question method, API returns control question text. Answer text entered by user must be supplied to this endpoint. If invalid answer is supplied, auth.controlanswer.invalid error code is returned.

On successful validation of control answer, a temporary session token with recovery-setpassword session state is returned. Client is expected to call auth/setpassword API endpoint next using this temporary session token.

Request Headers:
 
  • Authorization – Bearer <session_token> (session state must be recovery-checkotp)
Request JSON Object:
 
  • control_answer (string) – Answer to control question entered by user
Response JSON Object:
 
  • status (string) – success or error
  • error_code (string) – (Optional) If status is error: one of error codes listed below
  • session_token (string) – User session token
  • session_state (string) – User session state: recovery-setpassword. See User Sessions
  • password_regex (string/null) – Regex to check required password quality (check disabled if null)
  • password_regex_description (string/null) – Description text for password quality check

Error codes used

  • 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

See Error Codes for details.

Set Password

POST /(company_code)/v2/auth/setpassword

Set or change user password

This endpoint is used during authorization or access recovery process when authenticated user needs to set a new password.

If called during authorization (setpassword session state), new session token with authorized session state will be returned. profile_mnemocode response field will contain the mnemocode of user’s profile.

If called during access recovery (recovery-setpassword session state), no new session token will be returned. Client application should use auth/login endpoint next for authorization of user with recovered access.

If quality of supplied new password is too low, returns request.validation.failed error code with HTTP status code 422.

Request Headers:
 
  • Authorization – Bearer <session_token> (session state must be setpassword or recovery-setpassword)
Request JSON Object:
 
  • new_password (string) – New user password
Response JSON Object:
 
  • status (string) – success or error
  • error_code (string) – (Optional) If status is error: one of error codes listed below
  • session_token (string) – (Optional) If session state was setpassword: User session token
  • session_state (string) – (Optional) If session state was setpassword: User session state: authorized. See User Sessions
  • profile_mnemocode (string) – (Optional) If session state was setpassword: Mnemocode of user’s profile

Error codes used

  • 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

See Error Codes for details.