This API allows to get a validation status on a token.

This API allows Rainbow users to login.

The application is also authenticated during the user login.

If login is successful and multi-factor authentication isn't activated for user (or activated but not configured), the API returns a JSON Web Token (<abbr title="JSON Web Token">JWT) which has to be provided by clients for all Rainbow APIs requiring user authentication:

• The JWT is valid only for a given time period.
• The JWT can be renewed a few times using API GET /api/rainbow/authentication/v1.0/renew.
• The maximum number of renew is given in the JWT payload, as well as the current number of time the token has been renewed (see below).
• Once the JWT expired, or if the maximum of token renew has been reached, user must login again using this API.

The JWT returned contains the following data in payload:

{
    "countRenewed": 0,  // Number of times the token has been renewed
    "maxTokenRenew": 5,  // Number of times the token can be renewed
    "user": {
        "id": "572756967bfbca0d0e09a6b4",  // Logged in user id
        "loginEmail": "user@company.com"  // Logged in user loginEmail
    },
    "app": {
        "id": "598983029db9b5b14693a6f0",  // Application id used for the authentication
        "name": "My App"  // Application name
    },
    "iat": 1463588327,  // (Issued At) Time at which the JWT was issued
    "exp": 2183588327  // (Expiration Time) Expiration time after which the JWT won't be accepted
}

If the login / password combination is wrong, an error 401 is return (errorDetailsCode 401500).
If the appId / appSecret combination is wrong, an error 401 is return (errorDetailsCode 401500).

The following login protection is implemented:

• After a given number of login failure (5 by default), the user account is locked for a given time period (60 min by default).
• As long as the maximum number of login failure has not been reached, a 401 error with errorDetailsCode 401500 is returned.
• Once the maximum number of login attempts has been reached, a 401 error with errorDetailsCode 401501 is returned: the user account is locked for the given time period.
• While the user account is locked, the same response with errorDetailsCode 401501 will be returned for each new login attempt for this user account (even if a good login / password combination is provided). If the login / password combination is wrong, the locked time period restarts from this new wrong attempt.
• Once the locked time period is over, a login with the good credentials will be allowed.
• While the account is locked, the user can reset his password. In that case, his account will be unlocked and he will be able to login with his new password.
• While the account is locked, a superadmin / support / admin (organisation or company level) user can set a new password for this account. In that case, this account will be unlocked and the user will be able to login with this new password.

If multi-factor authentication is activated for the user and enabled, depending on the configuration of selected policy the API may return a JSON Web Token (<abbr title="JSON Web Token">JWT) which has to be provided by clients for all Rainbow MFA APIs requiring user authentication:

• The JWT is valid only for a short given time period.
• The JWT can't be renewed.
• Once the JWT expired, user must login again using this API.

The JWT returned contains the following data in payload:

{
   "maxTokenRenew": 0,  // Number of times the token can be renewed
   "user": {
       "id": "572756967bfbca0d0e09a6b4",  // Logged in user id
       "loginEmail": "user@company.com"  // Logged in user loginEmail
   },
   "app": {
       "id": "598983029db9b5b14693a6f0",  // Application id used for the authentication
       "name": "My App"  // Application name
   },
   "mfaType": "totp",
   "iat": 1463588327,  // (Issued At) Time at which the JWT was issued
   "exp": 2183588327  // (Expiration Time) Expiration time after which the JWT won't be accepted
}

Warning

• login url is case sensitive (lowercase). For example, /Login or /LOGIN won't work.
• login will be forbidden for a certain delay if too much consecutive wrong password errors occurs, after this user has to request a password change or just wait (see implementation details above).

This API allows Rainbow users to logout.

Note: This API must not be called with ApiKey as authentication method.

This API allows Rainbow users to renew their JSON Web Token (<abbr title="JSON Web Token">JWT), thus extending the expiration date of their current JWT.

This API requires user to be authenticated with a valid non expired JWT.

If so, a new JWT is returned, with the expiration date starting from now.

Warning:

• The JWT can only be renewed a given number of times, after this user has to login again to get a new token using API GET /api/rainbow/authentication/v1.0/login.
• The maximum number of renew is given in the JWT, as well as the current number of time the token has been renewed.
• This API must not be called with ApiKey as authentication method.