Skip to main content

Tokens

Overview​

This documentation outlines the recommended approach for logging into the CRS system and the expected usage patterns for access and refresh tokens.

Basics​

Most API methods require authorization. The server expects an Authorization header value within an HTTP request. The client must provide an access token obtained through one of the login methods before making a request.

  • Access Token: Short-lived, while refresh token's lifespan can be in scope of months.
  • Refresh Token: Long-lived (potentially months), used to obtain new access tokens without requiring user credentials again. This method is recommended for mobile applications as it doesn't require entering user name and password every time.

First Login​

There are several ways to login, most common one is Login method, accessible by path api/security/authentication/login. It accepts 3 parameters:

{
  "TenantDomainName": "<tenant>",
  "UserNameOrEmail": "<user name or email>",
  "Password": "<password>"
}

If the request passes validation, the server returns the following response:

{
  "modelType": "Response<LoginResult>",
  "errorOrValue": {
    "value": {
      "resultCode": 1,
      "token": "<access token>",
      "tokenId": "<access token id>",
      "expiresIn": "2021-11-02T13:53:53.000+03:00",
      "userInfo": {
        "id": <user id>,
        "displayName": "<user display name>",
        "tenantName": "<tenant>"
      },
      "refreshTokenInfo": {
        "tokenId": "<refresh token id>",
        "token": "<refresh token>",
        "expiresIn": "2021-11-02T13:53:53.558+03:00"
      }
    },
    "error": null
  }
}

The server returns both access and refresh tokens, each with an expiration time. These tokens should not be used after expiration.

Best Practices​

DO NOT

Common antipattern is to make a login call before each call to server. This results in a lot of refresh tokens being active for prolonged period of time which is potential security hazard. Moreover, login operation is time consuming by design, so by logging in before every call you decrease the performance of your system.

DO

Save both access and refresh tokens and provide access token value in Authorization header. When it expires, use LoginWithRefreshToken call to acquire new access token using stored refresh token (explained in more details below)

Refresh Token​

To be able to call server after access token expiration client should call LoginWithRefreshToken method accessible by path api/security/authentication/loginWithRefreshToken. Method does not require authorization header, therefore it can be used after access token expiration time (but before refresh token expiration). It accepts following parameters:

{
  "TenantDomainName": "<tenant>",
  "RefreshToken": "<refresh token>",
  "IssueRefreshToken": "true"
}

If IssueRefreshTokenis true, server will return new refresh token with new expiration time. Old used refresh token will be invalidated.

Last updated on