How to use tokens

This page describes suggested way to login to CRS system and expected usage patterns of access and refresh tokens.

1 Basics
2 First login
3 Refresh token

Basics

Most of API methods require authorization. Server expects to receive Authorization header value inside HTTP request. As header value client should provide access token acquired before that moment by any of login methods.

Access token is relatively short lived, while refresh token's lifespan can be in scope of months. Refresh token is used for acquiring new access token when old one expires. Logging in with refresh token doesn't require entering user name and password once again, so it's a preferable login method for mobile applications.

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 request passes the validation server will return 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
  }
}

Server returns access and refresh tokens. Both tokens have expiration time and should not be used after that.

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.