User Login¶

Login Process Flow
Check Login ID
Check Password
Check OTP
Renew OTP
Set Password
Check Credentials
OAuth Login
Accept Disclaimers
Log Out

Check Login ID ¶

POST /(company_code)/v2/auth/login¶

User login (login ID verification)

Verifies user login ID (can be primary phone, primary email, or a separate login name depending on user role) and issues a temporary user session token for further authentication. This token is returned in session_token response field and must be used when calling respective authentication endpoints.

If user profile for supplied login ID is not found, returns auth.loginid.notfound error code 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.

If user profile has a password set, session_state response field will be set to checkpassword. Client application should call auth/checkpassword endpoint next supplying received session token.

If user profile does not have a password set, session_state response field will be set to checkotp. Client application should call auth/checkotp endpoint next supplying received session token and one-time SMS code entered by user.

If user needs to accept legal disclaimers, disclaimers_required array in response will contain data of required disclaimers. auth/checkpassword and auth/checkotp endpoints will not succeed unless supplied list of accepted disclaimers contains codes of all required disclaimers.

Request JSON Object:
	login_id (string) – User login ID (primary phone, primary email, or a separate login name)
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: `checkpassword` or `checkotp`. See User Sessions disclaimers_required (array) – Array of data objects of legal disclaimers that user needs to accept captcha_required (boolean) – (Optional) If `session_state` is `checkpassword`: `true` if next request must have `captcha_response` field set user_phone (string) – (Optional) If `session_state` is `checkotp`: masked user’s phone number

Disclaimer fields

Each member of disclaimers_required response array is an object with following fields:

Field name	Type	Nullable	Description
code	string	No	Disclaimer code
title	string	No	Disclaimer title for display
description	string	No	Short disclaimer description
link	string	No	URL for link to legal disclaimer text

Error codes used

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

See Error Codes for details.

Check Password ¶

POST /(company_code)/v2/auth/checkpassword¶

Check user password for authentication

If invalid password was supplied, auth.password.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.

If user needs to accept legal disclaimers, accept_disclaimers array in request must contain codes of all required disclaimers for this endpoint to succeed. Otherwise, auth.disclaimer.invalid error code is returned and disclaimers_required response field is set to array of required disclaimers.

If second factor verification is required, a temporary session token with checkotp session state is returned. Client is expected to call auth/checkotp API endpoint next using this temporary session token. user_phone response field is set to masked user’s phone number for SMS verification.

If user is required to set a new password, a temporary session token with setpassword session state is returned. Client is expected to call auth/setpassword API endpoint next using this temporary session token.

If no further authorization actions are required, returned session token will have authorized session state. profile_mnemocode response field will contain the mnemocode of user’s profile for Profile API endpoints.

Request Headers:
	Authorization – `Bearer <session_token>` (session state must be `checkpassword`)
Request JSON Object:
	password (string) – Password entered by user captcha_response (string) – (Optional) User captcha response token, as provided by Recaptcha accept_disclaimers (array) – (Optional) Array of string codes of disclaimers accepted by user
Response JSON Object:
	status (string) – `success` or `error` error_code (string) – (Optional) If `status` is `error`: one of error codes listed below captcha_required (boolean) – (Optional) If `status` is `error`: `true` if next request must have `captcha_response` field set disclaimers_required (array) – (Optional) If `status` is `error`: Array of data objects of legal disclaimers that user needs to accept session_token (string) – User session token session_state (string) – User session state: `checkotp`, `setpassword`, or `authorized`. See User Sessions profile_mnemocode (string) – (Optional) If `session_state` is `authorized`: Mnemocode of user’s profile user_phone (string) – (Optional) If `session_state` is `checkotp`: masked user’s phone number password_regex (string/null) – (Optional) If `session_state` is `setpassword`: Regex to check required password quality (check disabled if `null`) password_regex_description (string/null) – (Optional) If `session_state` is `setpassword`: Description text for password quality check

Disclaimer fields

Each member of disclaimers_required response array is an object with following fields:

Field name	Type	Nullable	Description
code	string	No	Disclaimer code
title	string	No	Disclaimer title for display
description	string	No	Short disclaimer description
link	string	No	URL for link to legal disclaimer text

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
auth.captcha.missing
auth.captcha.invalid
auth.password.invalid
auth.disclaimer.invalid
auth.restricted
request.validation.failed

See Error Codes for details.

Check OTP ¶

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

Check one-time password for authentication

For OTP authentication, a one-time password (code) is sent to user’s primary phone number. API response includes user_phone field containing masked user’s phone number. OTP entered by user must be supplied to this endpoint in the otp request field. If invalid OTP is supplied, auth.otp.invalid error code is returned. auth/renewotp endpoint must be used to send a new OTP before retrying this endpoint.

If user does not have access to phone, they can choose to use a previously generated backup code instead of SMS OTP. This code must be supplied in the backup_code request field. If invalid code is supplied, auth.backupcode.invalid error code is returned.

If user needs to accept legal disclaimers, accept_disclaimers array in request must contain codes of all required disclaimers for this endpoint to succeed. Otherwise, auth.disclaimer.invalid error code is returned and disclaimers_required response field is set to array of required disclaimers. auth/renewotp endpoint must be used to send new SMS OTP before retrying this endpoint.

If user is required to set a new password, a temporary session token with setpassword session state is returned. Client is expected to call auth/setpassword API endpoint next using this temporary session token.

If no further authorization actions are required, returned session token will have authorized session state. profile_mnemocode response field will contain the mnemocode of user’s profile for Profile API endpoints.

Request Headers:
	Authorization – `Bearer <session_token>` (session state must be `checkotp`)
Request JSON Object:
	otp (string) – (Optional) SMS one-time password entered by user backup_code (string) – (Optional) Backup code entered by user accept_disclaimers (array) – (Optional) Array of string codes of disclaimers accepted by user
Response JSON Object:
	status (string) – `success` or `error` error_code (string) – (Optional) If `status` is `error`: one of error codes listed below disclaimers_required (array) – (Optional) If `status` is `error`: Array of data objects of legal disclaimers that user needs to accept session_token (string) – User session token session_state (string) – User session state: `setpassword` or `authorized`. See User Sessions profile_mnemocode (string) – (Optional) If `session_state` is `authorized`: Mnemocode of user’s profile password_regex (string/null) – (Optional) If `session_state` is `setpassword`: Regex to check required password quality (check disabled if `null`) password_regex_description (string/null) – (Optional) If `session_state` is `setpassword`: Description text for password quality check

Disclaimer fields

Each member of disclaimers_required response array is an object with following fields:

Field name	Type	Nullable	Description
code	string	No	Disclaimer code
title	string	No	Disclaimer title for display
description	string	No	Short disclaimer description
link	string	No	URL for link to legal disclaimer text

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
auth.otp.invalid
auth.backupcode.invalid
auth.disclaimer.invalid
auth.restricted
request.validation.failed

See Error Codes for details.

Renew OTP ¶

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

Renew one-time password for authentication

A new one-time password (code) is sent to user’s primary phone number. user_phone response field contains masked user’s phone number.

Request Headers:
	Authorization – `Bearer <session_token>` (session state must be `checkotp`)
Response JSON Object:
	status (string) – `success` or `error` error_code (string) – (Optional) If `status` is `error`: one of error codes listed below user_phone (string) – Masked user’s phone number

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.

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.

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.

If user needs to accept legal disclaimers, accept_disclaimers array in request must contain codes of all required disclaimers for this endpoint to succeed. Otherwise, auth.disclaimer.invalid error code is returned and disclaimers_required response field is set to array of required disclaimers.

If second factor verification is required, a temporary session token with checkotp session state is returned. Client is expected to call auth/checkotp API endpoint next using this temporary session token. user_phone response field is set to masked user’s phone number for SMS verification.

If user is required to set a new password, a temporary session token with setpassword session state is returned. Client is expected to call auth/setpassword API endpoint next using this temporary session token.

If no further authorization actions are required, returned session token will have authorized session state. profile_mnemocode response field will contain the mnemocode of user’s profile for Profile API endpoints.

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) password (string) – Password entered by user captcha_response (string) – (Optional) User captcha response token, as provided by Recaptcha accept_disclaimers (array) – (Optional) Array of string codes of disclaimers accepted by user
Response JSON Object:
	status (string) – `success` or `error` error_code (string) – (Optional) If `status` is `error`: one of error codes listed below captcha_required (boolean) – (Optional) If `status` is `error`: `true` if next request must have `captcha_response` field set disclaimers_required (array) – (Optional) If `status` is `error`: Array of data objects of legal disclaimers that user needs to accept session_token (string) – User session token session_state (string) – User session state: `checkotp`, `setpassword`, or `authorized`. See User Sessions profile_mnemocode (string) – (Optional) If `session_state` is `authorized`: Mnemocode of user’s profile user_phone (string) – (Optional) If `session_state` is `checkotp`: masked user’s phone number password_regex (string/null) – (Optional) If `session_state` is `setpassword`: Regex to check required password quality (check disabled if `null`) password_regex_description (string/null) – (Optional) If `session_state` is `setpassword`: Description text for password quality check

Disclaimer fields

Each member of disclaimers_required response array is an object with following fields:

Field name	Type	Nullable	Description
code	string	No	Disclaimer code
title	string	No	Disclaimer title for display
description	string	No	Short disclaimer description
link	string	No	URL for link to legal disclaimer text

Error codes used

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

See Error Codes for details.

OAuth Login ¶

POST /(company_code)/v2/auth/oauth¶

Authenticate user with OAuth provider

Verifies OAuth user authorization code with one of configured OAuth providers and returns a user session token.

If verification with OAuth provider failed, possibly due to invalid code or redirect_uri, returns auth.oauth.failed error code with HTTP status code 401.

If user profile for verified user of OAuth provider is not found, returns auth.oauth.notfound error code with HTTP status code 404.

If user authorization for user authenticated with OAuth is restricted, returns auth.user.restricted error code with HTTP status code 403.

If user profile for user authenticated with OAuth is closed, returns auth.user.closed error code with HTTP status code 403.

If service is administratively denied for user authenticated with OAuth, returns auth.user.denied error code with HTTP status code 403.

If user needs to accept legal disclaimers, session_state response field will be set to acceptdisclaimers and disclaimers_required array in response will contain data of required disclaimers. Client application should call auth/acceptdisclaimers endpoint next supplying received session token and list of accepted disclaimers.

If user does not need to accept legal disclaimers, returned session token will have authorized session state. profile_mnemocode response field will contain the mnemocode of user’s profile for Profile API endpoints.

Request JSON Object:
	provider_id (integer) – ID of OAuth provider, must be in range of 1 to 5 code (string) – OAuth code, as received from OAuth provider redirect_uri (string) – Redirect URI, as passed to OAuth provider
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: `authorized` or `acceptdisclaimers`. See User Sessions disclaimers_required (array) – (Optional) If `session_state` is `acceptdisclaimers`: Array of data objects of legal disclaimers that user needs to accept profile_mnemocode (string) – (Optional) If `session_state` is `authorized`: Mnemocode of user’s profile

Disclaimer fields

Each member of disclaimers_required response array is an object with following fields:

Field name	Type	Nullable	Description
code	string	No	Disclaimer code
title	string	No	Disclaimer title for display
description	string	No	Short disclaimer description
link	string	No	URL for link to legal disclaimer text

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.oauth.notfound
auth.oauth.failed
request.validation.failed
auth.user.restricted
auth.user.closed
auth.user.denied

See Error Codes for details.

Accept Disclaimers ¶

POST /(company_code)/v2/auth/acceptdisclaimers¶

Accept legal disclaimers during authorization

Issues a session token with authorized session state. profile_mnemocode response field will contain the mnemocode of user’s profile for Profile API endpoints.

accept_disclaimers array in request must contain codes of all required disclaimers for this endpoint to succeed. Otherwise, auth.disclaimer.invalid error code is returned and disclaimers_required response field is set to array of required disclaimers.

Request Headers:
	Authorization – `Bearer <session_token>` (session state must be `acceptdisclaimers`)
Request JSON Object:
	accept_disclaimers (array) – (Optional) Array of string codes of disclaimers accepted by user
Response JSON Object:
	status (string) – `success` or `error` error_code (string) – (Optional) If `status` is `error`: one of error codes listed below disclaimers_required (array) – (Optional) If `status` is `error`: Array of data objects of legal disclaimers that user needs to accept session_token (string) – User session token session_state (string) – User session state: `authorized`. See User Sessions profile_mnemocode (string) – Mnemocode of user’s profile

Disclaimer fields

Each member of disclaimers_required response array is an object with following fields:

Field name	Type	Nullable	Description
code	string	No	Disclaimer code
title	string	No	Disclaimer title for display
description	string	No	Short disclaimer description
link	string	No	URL for link to legal disclaimer text

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
auth.disclaimer.invalid
auth.restricted
request.validation.failed

See Error Codes for details.

Log Out ¶

POST /(company_code)/v2/auth/logout¶

User logout (invalidate auth token)

Request Headers:
	Authorization – `Bearer <session_token>`
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.token.invalid
auth.token.expired
auth.session.invalid

See Error Codes for details.

Table Of Contents

Related Topics

This Page