This API allows Rainbow users to know that URL they can use to perform a login.

The authentication URLs depends of the user and/or his company's setting:

• user can be configured to use:
  • Rainbow passwordless authentication
  • Rainbow password + MFA authentication
  • Rainbow password authentication
  • Single Sign On (SSO) authentication (OIDC, SAML, global SSO method when available)
  • Company's default authentication method
• When user is not configured to use a specific authentication method, the company can be configured so its users use a given authentication method:
  • Rainbow passwordless authentication
  • Rainbow password + MFA authentication
  • Single Sign On (SSO) authentication (OIDC, SAML, global SSO method when available)

If no authentication method is configured on the user nor on its company, Rainbow password authentication method is used.

Rainbow passwordless authentication requires the user to have the feature SECURITY_PASSWORDLESS in his profile. If that is not the case, Rainbow password authentication method is used even if the user is configured to use passwordless authentication.

Some advanced user/device authentication performed by some SSO servers (Microsoft's conditional access, FIDO, Yubikey...) are not correctly handled by Rainbow Desktop application (Electron based). In order to bye-pass these limitations, company's SSO settings can be configured to be performed in user's browser instead of inside the Desktop client. This remote authentication mechanism is named backchannel in this documentation.

To be noted that whatever the authentication configuration, admin users always have the Rainbow password authentication method returned (fallback in case of authentication configuration issues).

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.

This API allows the user to get a once-time access code (OTP) to be used for passwordless login. This access code has then to be provided to the API POST /api/rainbow/authentication/v1.0/passwordless/login in order to proceed to the passwordless authentication and retrieve a JWT token.

This API is meant to be used by users configured to use passwordless authentication method:

• either they are configured to use their company's default authentication method (their setting authenticationType is not set) and their company's default authentication method is a rainbowPasswordlessPolicies (authentication setting having enabledForAllCompanyUsers set to true)
• either they are configured to use a given rainbowPasswordlessPolicies of their company (their setting authenticationType is set to RAINBOW and their rainbowPasswordlessPolicy.rainbowPasswordlessPolicyId is set to one of their company's rainbowPasswordlessPolicies) The user must have the feature SECURITY_PASSWORDLESS in his profile.

Depending on their company's rainbowPasswordlessPolicies configured for the user:

• the code is sent by email and/or by SMS.
• the code length is between 6 and 10 digits,
• the code duration is between 60 seconds (1 minute) to 86400 seconds (24 hours)

The access code:

• can only be used once (it is revoked once the user authenticates with this code)
• is revoked if a new one is generated for the same uid
• is revoked once its expiration date is reached

A user can only request up to 5 codes per hour without success authentication. If the user requests a 6th code in less than 1 hour, an error 403538 is returned.

This API allows Rainbow users to use a once-time access code (OTP) in order to login to Rainbow.

This API is meant to be used by users configured to use passwordless authentication method:

• either they are configured to use their company's default authentication method (their setting authenticationType is not set) and their company's default authentication method is a rainbowPasswordlessPolicies (authentication setting having enabledForAllCompanyUsers set to true)
• either they are configured to use a given rainbowPasswordlessPolicies of their company (their setting authenticationType is set to RAINBOW and their rainbowPasswordlessPolicy.rainbowPasswordlessPolicyId is set to one of their company's rainbowPasswordlessPolicies) The user must have the feature SECURITY_PASSWORDLESS in his profile.

The access code to set in this API is obtained using with the API GET /api/rainbow/authentication/v1.0/passwordless/code.

The application is also authenticated during the user login.

If login is successful, 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 uid / code combination is wrong, an error 401 is return (errorDetailsCode 401610).
If the appId / appSecret combination is wrong, an error 401 is return (errorDetailsCode 401500).

The following login protection is implemented:

• After 5 login failure, the user account is locked for 1 hour.
• As long as the maximum number of login failure has not been reached, a 401 error with errorDetailsCode 401610 is returned.
• Once the maximum number of login attempts has been reached, a 401 error with errorDetailsCode 401611 is returned: the user account is locked for the given time period.
• While the user account is locked, the same response with errorDetailsCode 401611 will be returned for each new login attempt for this user account (even if a good uid / code combination is provided). If the uid / code combination is wrong, the locked time period restarts from this new wrong attempt.
• Once the locked time period is over, a login with a valid uid / code combination will be allowed.

This API allows Rainbow users to login using OpenID Connect (OIDC) authentication (using authorization code grant) if this type of authentication is provided by their company.

Authorization code grant is recommended as it is more secure than Implicit grant (it involves a clientSecret from Rainbow application). This API is dedicated to Authorization code grant, the OIDC flow being completely handled by Rainbow authentication server.

In order to use this API, the OIDC SingleSignOn settings of the company must contain:

• clientId: the client_id for the Rainbow application created on the company's OIDC provider,
• clientSecret: the client_secret for the Rainbow application created on the company's OIDC provider,
• issuer: the company's OIDC provider issuer (should has been got from discoveryUrl if OIDC settings has been configured with this parameter).
• authorizationEndpoint: the company's OIDC provider authorization endpoint (should has been got from discoveryUrl if OIDC settings has been configured with this parameter).
• tokenEndpoint: the company's OIDC provider token endpoint (should has been got from discoveryUrl if OIDC settings has been configured with this parameter).
• jwksUri: the company's OIDC provider jwks_uri endpoint (should has been got from discoveryUrl if OIDC settings has been configured with this parameter).

The full OIDC flow using Authorization Code grant is detailed in the following sequence diagram.

This GET /api/rainbow/authentication/v1.0/oidc-client/login endpoint addresses points 3 to 7 of this diagram (point 2 is addressed by GET /api/rainbow/authentication/v1.0/urls?uid=user@company.com endpoint, see related documentation).

Details about the sequence diagram:

• (1) User starts application
• (2) Application requests Rainbow Authentication portal’s API GET /api/rainbow/authentication/v1.0/urls?uid=user@company.com

  to know what is the authentication type to use for this user.

• (3) In the case the authentication type is OIDC for this user, the application has to redirect the browser / open a web view to this URL.
  • x-rainbow-app-auth field has to be provided in query parameters to authenticate the application (sha256 hash is computed using the challenge)
• Rainbow Authentication portal implements the OIDC authorization code grant flow:
  • (4) Rainbow Authentication portal redirects the browser to the OIDC server’s authorize endpoint,
  • (5) user enter his credentials in the OIDC server’s login page,
  • (6) OIDC server send an authorization_code to a redirect_uri on Rainbow Authentication portal,
  • (6) Rainbow Authentication portal calls OIDC server’s token endpoint to exchange this authorization_code against an id_token,
  • (6) Rainbow Authentication portal decodes the id_token, looks for a Rainbow user with this email as loginEmail,

    finds the OIDC SSO setting of his company and validates the id_token
    (validation of id_token signature, id_token expiration, issuer and audience fields).

• (7) Rainbow Authentication portal generates a Rainbow JWT and redirects the browser to the application’s

  ssoAuthenticationRedirectUrl (default to Official Rainbow web client) with this jwt in query string (tkn query parameter).

• (8) Rainbow JWT can be use to call Rainbow APIs

In the case errors occur during the OIDC client login flow, the browser is redirected to the application’s ssoAuthenticationRedirectUrl (default to Official Rainbow web client) with the following query parameters:

• errtype: always set to OIDC for errors returned by this API,
• errcode: an error detailed code associated to the error (ex: 401500)
• errmsg: an error message code associated to the error (ex: Unknown application or wrong token for application id 204583b32039df11e9a07425538fb36c74)

This API allows Rainbow users to login using SAML authentication if this type of authentication is provided by their company.

This endpoints allows applications to get authorization from Rainbow users to use Rainbow APIs with their account. This delegation of access can be performed using OAuth 2.0 Authorization code grant or Implicit grant.

While both OAuth 2.0 Authorization Code grant and Implicit grant are supported by Rainbow, Authorization Code grant is recommended as it is more secure.

Implicit grant is recommended for browser applications implemented in JavaScript that can't provide a backend server handling the token exchange flow of OAuth Authorization Code grant. Indeed, such applications should not embed appSecret in their source code for security reasons, and Implicit grant allow them to retrieve the OAuth access token without sending the appSecret to Rainbow server (redirect_uri is the only security available with this flow). The limitation of implicit grant is that only an access token is returned, which has a limited lifetime and can't be renewed. Application has to execute again the whole Implicit grant flow to retrieve a new access token.

To enable Implicit grant for an application, the application's setting enableOAuthImplicitGrant has to be set to true (it is disabled by default).

For more information, see the OAuth 2.0 RFC related to authorization endpoint:

• section 4.1.1 for Authorization Code grant,
• section 4.2.1 for Implicit grant.

Note that Rainbow applications are named client in OAuth 2.0 RFC.

1. Authorize request for Authorization code grant

The OAuth Authorization Code Grant flow is detailed in the following sequence diagram.

This GET /api/rainbow/authentication/v1.0/oauth/authorize endpoint addresses points 1 to 7 of this diagram for Authorization code grant flow (points 8 to 9 are addressed by POST /api/rainbow/authentication/v1.0/oauth/token endpoint).

Details about the sequence diagram:

• (1) User is on application website

• (1) User accesses to application content that needs data from Rainbow, or application allows to login with Rainbow,

  … (use case depends of the application needs)

• (2) Application redirects to OAuth authorize endpoint on Rainbow authentication server.

  Some query string parameters are provided in the query (defined by OAuth 2.0 RFC):

  • response_type: "code" for requesting an authorization code (authorization code grant)
  • client_id: the application identifier (appId)
  • redirect_uri: application's backend endpoint where the authorization code will be sent.
    It has to use TLS for security reasons, as the authorization code is exchanged between Rainbow and the application's backend through the browser.
  • scope: scope of the access requested by the application.
    Currently, only "all" is supported (meaning that the application will have full access on all the Rainbow APIs).
    In a next step, scopes will be defined so that the application can request restricted scopes (filestorage, bubble management, channels, …)
  • state: a "random" value sent by the client to maintain a state between the request and the callback. Can be used to protect against cross-site request forgery attacks (CSRF).

• (3) Rainbow authentication server checks that the client_id sent in query parameter in (2) corresponds to a valid application in the database.

  • If so, Rainbow authentication server redirects user's browser to Rainbow login page
  • Otherwise, an error is returned (if redirect_uri is provided, user's browser is redirected to this uri and the error is sent in query parameters)

• (4) User enters his credentials on login page and submit the form. Rainbow authentication server checks in the database if user credentials are valid.

  • If user credentials are incorrect, Rainbow authentication server redirects again user's browser to login page with an error which is displayed for the user.
  • If user credentials are valid, Rainbow authentication server checks if the user authentication requires a 2nd factor (MFA).
    • If 2nd factor is required, user's browser is redirected to mfa page.
      User enters his 2nd factor and submit the form. Rainbow authentication server checks if user's 2nd factor is valid. Note: user can also enter his recovery code (if recovery code is valid, user authentication is granted and MFA is disabled for this user).
      • If user's 2nd factor is incorrect, Rainbow authentication server redirects again user's browser to mfa page with an error which is displayed for the user

• (5) Rainbow authentication server redirects user's browser to consent page (except if app's setting disableOAuthConsentScreen is true, in this case step (6) is skipped).

• (6) User authorize the application to access Rainbow APIs in his name. The form is submitted on Rainbow authentication server.

  • (7) If the user authorized, Rainbow authentication server generates an authorization code and redirects user's browser to application backend's redirect_uri (the one provided in query parameters in (2)).

    Note that redirect_uri must be one of the configured oauthRedirectUris in the application, otherwise an error is returned.

    The following data are returned in query parameters of the redirection uri (defined by OAuth 2.0 RFC):

    • code: the authorization code that can be exchanged against an access token and a refresh token using token endpoint. Authorization code has a short lifetime (10 minutes) and can only be used once.
    • state: if state was provided in (2), this value is returned (otherwise a random value is returned).

  • If the user declined, Rainbow authentication server redirects user's browser to application backend's redirect_uri with an error in query parameters.

Once the application has the authorization code, it has to exchange it against an access token and a refresh token using POST /api/rainbow/authentication/v1.0/oauth/token endpoint, points 8 and 9 of the sequence diagram (see documentation of this endpoint for more information).

2. Authorize request for Implicit grant

The OAuth Implicit Grant flow is detailed in the following sequence diagram.

Unlike Authorization Code grant flow, this GET /api/rainbow/authentication/v1.0/oauth/authorize endpoint is the only one to be used by the application to retrieve the OAuth access token.

Details about the sequence diagram:

• (1) User uses the web application on his browser

• (1) User accesses to web application content that needs data from Rainbow, or web application allows to login with Rainbow, … (use case depends of the application needs)

• (2) Application redirects to OAuth authorize endpoint on Rainbow authentication server.

  Some query string parameters are provided in the query (defined by OAuth 2.0 RFC):

  • response_type: "token" for requesting an access token (implicit grant)
  • client_id: the application identifier (appId)
  • redirect_uri: web application's endpoint where the authorization code will be sent.
  • scope: scope of the access requested by the application.
    Currently, only "all" is supported (meaning that the application will have full access on all the Rainbow APIs).
    In a next step, scopes will be defined so that the application can request restricted scopes (filestorage, bubble management, channels, …)
  • state: a "random" value sent by the client to maintain a state between the request and the callback. Can be used to protect against cross-site request forgery attacks (CSRF).

• (3) Rainbow authentication server checks that the client_id sent in query parameter in (2) corresponds to a valid application in the database.

  • If so, Rainbow authentication server redirects user's browser to Rainbow login page
  • Otherwise, an error is returned (if redirect_uri is provided, user's browser is redirected to this uri and the error is sent in fragment component of this redirection uri)

• (4) User enters his credentials on login page and submit the form. Rainbow authentication server checks in the database if user credentials are valid.

  • (5) If so, Rainbow authentication server redirects user's browser to consent page
  • Otherwise, Rainbow authentication server redirects again user's browser to login page with an error which is displayed for the user

• (6) User authorize the application to access Rainbow APIs in his name. The form is submitted on Rainbow authentication server.

  • (7) If the user authorized, Rainbow authentication server generates an access token and redirects user's browser to web application's redirect_uri (the one provided in query parameters in (2)).

    Note that redirect_uri must be one of the configured oauthRedirectUris in the application, otherwise an error is returned.

    The following data are returned in fragment component of the redirection uri (defined by OAuth 2.0 RFC):

    • access_token: the access token that can be used by the application to use Rainbow APIs,
    • token_type: the type of token returned ("access_token"),
    • expires_in: the lifetime of the access token (in seconds),
    • state: if state was provided in (2), this value is returned (otherwise a random value is returned).

  • If the user declined, Rainbow authentication server redirects user's browser to application's redirect_uri with an error in fragment component.

Once the application has the access token, it can use it to use Rainbow APIs with the account of the related Rainbow user.

This endpoints allows applications to get an access token allowing them to use Rainbow APIs with the account of the related Rainbow user.

Access token has a short lifetime (1 hour). A refresh token is issued as well, allowing applications to refresh their access token (and such avoiding the application to request user authorization again with GET /api/rainbow/authentication/v1.0/oauth/authorize).

The token endpoint can be used:

1. To exchange the authorization code against an access token and a refresh token,
2. To get a new access token using the refresh token (to be used when the access token has expired).

1. Exchange the authorization code against an access token and a refresh token

For more information, see the OAuth 2.0 RFC, section 4.1.3 related to the use of this endpoint to exchange the authorization code against an access token and a refresh token.

The OAuth Access Token Request flow is detailed in the following sequence diagram.

This POST /api/rainbow/authentication/v1.0/oauth/token endpoint addresses points 8 to 9 of this diagram (points 1 to 7 are addressed by GET /api/rainbow/authentication/v1.0/oauth/authorize endpoint).

Details about the sequence diagram:

• (8) application's backend exchanges the authorization code it retrieved in (7) against an access token and a refresh token.

  For that, it calls the OAuth token endpoint on Rainbow authentication server. It has to provide:

  • The header Authorization with Basic <base64encode(client_id:client_secret)>.

    This request has to be done from the application''s backend so that the client_secret (appSecret) remains confidential.

    Example of base64 calculation:

    base64("78e98ee09bad11e8b8edebb50d679df6:2UrOcs3agk34zaV3Jsf01vM54iLyqwBEpnv5vJr72D9cE5wMVQeEe3BM7IxzyyJD") =
      <i>NzhlOThlZTA5YmFkMTFlOGI4ZWRlYmI1MGQ2NzlkZjY6MlVyT2NzM2FnazM0emFWM0pzZjAxdk01NGlMeXF3QkVwbnY1dkpyNzJEOWNFNXdNVlFlRWUzQk03SXh6eXlKRA==</i>

• In the body the parameters (x-www-form-urlencoded):

• grant_type: must be set to "authorization_code" for an exchange of an authorization code against an access token and a refresh token

• code: the authorization code sent by Rainbow authentication server in (7)

• redirect_uri: the redirect_uri parameter, must be the same than the one used to retrieve the authorization code (the one sent in (2))

  • (9) Rainbow authentication server checks that the application's credentials are valid by extracting client_id and client_secret from the Authorization header and comparing them to the appId and appSecret stored in the database. Then it checks that the provided authorization code is valid, has well been generated for this application and redirect_uri matches the one sent in (2). Provided authorization code is revoked, as it can only be used once.
  • If everything is valid, Rainbow authentication server generates an access token and a refresh token that it stores in the database and returns in the body of the HTTP response to the application's backend.
  • Otherwise, a body with an error message is returned to the application's backend.
  • (10) With the access token received from the Rainbow authentication server in (9), the application can use it to call Rainbow APIs in the name of the user.

  For that, it calls the Rainbow APIs with the header Authorization Bearer .

2. Refresh an access token

Access token has a short lifetime (1 hour). If the application tries to use an expired access token for a request on Rainbow API, an error 401 Unauthorized is returned. Access token can be renewed using the refresh token, this avoids the application to redo the whole OAuth authorization code flow.

For more information, see the OAuth 2.0 RFC, section 6 related to the refresh of an access token.

The OAuth Refresh Access Token flow is detailed in the following sequence diagram. Details about the sequence diagram:

• (1) User is on application website

• (1) User accesses to application content that needs data from Rainbow (use case depends of the application needs).

  The application has already an OAuth access token and a refresh token retrieved using the authorization code grant described in "OAuth Authorization Code Grant sequence diagram".

• (1) Application calls the Rainbow API (whatever the portal is) to access Rainbow user data. It provides the header Authorization: Bearer <access_token> in the request.

• (2) Rainbow API portal checks the validity of the access token (existing, not expired).

• (2) If the access token is expired, an error 401 Unauthorized is returned. The application needs to renew the access token.

• (3) [optional, depends of the application implementation] If the application is executed in the browser (JavaScript), it needs to request its backend to get a new access token.

  If the request to Rainbow API is already performed in the application's backend, the backend itself can renew the access token.

• (4) Application's backend calls the OAuth token endpoint on Rainbow authentication server. It has to provide:

  • The header Authorization with Basic <base64(client_id:client_secret)>. This request has to be done from the application's backend so that the client_secret (appSecret) remains confidential.

 Example of base64 calculation:

 base64("78e98ee09bad11e8b8edebb50d679df6:2UrOcs3agk34zaV3Jsf01vM54iLyqwBEpnv5vJr72D9cE5wMVQeEe3BM7IxzyyJD") =
        <i>NzhlOThlZTA5YmFkMTFlOGI4ZWRlYmI1MGQ2NzlkZjY6MlVyT2NzM2FnazM0emFWM0pzZjAxdk01NGlMeXF3QkVwbnY1dkpyNzJEOWNFNXdNVlFlRWUzQk03SXh6eXlKRA==</i>

• In the body the parameters (x-www-form-urlencoded)

  • grant_type: must be set to "refresh_token" to request a new access token using the refresh token
  • refresh_token: the refresh token sent by Rainbow authentication server
    • (5) Rainbow authentication server checks that the client credentials are valid by extracting client_id and client_secret from the Authorization header and comparing them to the appId and appSecret stored in the database. Then it checks that the provided refresh token is valid, not expired, and has well been generated for this application.
    • If everything is valid, Rainbow authentication server generates a new access token and returns both access token and refresh token in the body of the HTTP response to the application's backend.
      If the enableOAuthRefreshTokenRotation setting is enabled for this application (it is enabled by default), a new refresh token is also generated and this new one is returned in the body of the HTTP response. The current refresh token is then revoked.
    • Otherwise, a body with an error message is returned to the application's backend.
    • (6) The application updates its access token and refresh token in its own storage.

  In the case the application is running in the browser, the backend returns the new access token to its frontend.

  • (7) The application redo the same API request to Rainbow portal done in (1), with the newly generated access token.
  • (8) Rainbow API portal checks the validity of the access token. As the access token is now valid, the Rainbow API performs the requested operation / returns the requested data.