Authentication & Authorization

API Endpoints

User Sessions

User session is identified with session token, which needs to be supplied by the client in Authorization header:

Authorization: Bearer <session_token>

To authorize user with the API service, client must use authentication endpoints. Upon successful authentication, session token is returned in the session_token field. Response also includes session_state field identifying current session authorization state. Session state code can be one of the following strings:

authorized
User is successfully authenticated and authorized. Client can make regular API requests using received session token.
checkpassword
To authorize user, client application must provide user password to auth/checkpassword endpoint using the received temporary session token. Upon successful validation, a new session token is returned with authorized, checkotp, or setpassword session state. The new token must be used for further requests.
checkotp
To authorize user, client application must provide One-Time Password to auth/checkotp endpoint using the received temporary session token. Upon successful validation, a new session token is returned with authorized or setpassword session state. The new token must be used for further requests.
setpassword
User is successfully authenticated and required to set a new password using auth/setpassword endpoint with the received temporary session token. When new password is successfully set, a new session token is returned with authorized session state. The new token must be used for further requests.
recovery-checkotp
To recover access with phone method, client application must provide One-Time Password to auth/recovery/checkotp endpoint using the received temporary session token. Upon successful validation, a new session token is returned with recovery-setpassword session state. The new token must be used for further requests.
recovery-checkquestion
To recover access with control question method, client application must provide control answer to auth/recovery/checkquestion endpoint using the received temporary session token. Upon successful validation, a new session token is returned with recovery-setpassword session state. The new token must be used for further requests.
recovery-setpassword
User is authenticated for access recovery and required to set a new password using auth/setpassword endpoint with the received temporary session token. When new password is successfully set, client application should start regular authentication process with auth/login endpoint.
acceptdisclaimers
User is successfully authenticated and required to accept legal disclaimers using auth/acceptdisclaimers endpoint with the received temporary session token. When disclaimers are accepted, a new session token is returned with authorized session state. The new token must be used for further requests.

Session Tokens

JSON Web Tokens (JWT) format with JWS Compact Serialization is used for session tokens. Client applications never generate these tokens but can use session information encoded in fields (claims) of a session token. Data fields can be obtained from JWT like this:

  1. JWT consists of three parts delimited by dots (.), the second (middle) part should be extracted for payload
  2. Payload text must be decoded using Base64url encoding
  3. Decoded payload text is valid JSON that can be parsed with standard tools

Payload for session tokens has these fields useful for client applications:

exp (integer)
Session expiration time as POSIX timestamp. If an expired token is supplied to an API endpoint requiring authorization, auth.token.expired error code will be returned with HTTP 401 status.
session_state (string)
Session state code, as described earlier. If an endpoint requires a different session state, auth.session.invalid error code will be returned with HTTP 401 status.