How to use tokens

This page describes suggested way to login to CRS system and use of access and refresh tokens.

Basics

Most of API method requires authorization. Server expects to receive Authorization header value. As value client should use access token provided by any of login method.

First login

There are several methods to login, basic 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 all sent values are correct 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 can be used until that moment only.

Access token intended to be saved and used within subsequent calls to server. It is not recommended to login before each call to server.

Refresh token

To continue being 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 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.