This page describes suggested way to login to CRS system and use expected usage patterns of access and refresh tokens.
| Table of Contents |
|---|
Basics
Most of API method requires methods require authorization. Server expects to receive Authorization header value inside HTTP request. As header value client should use provide access token provided acquired before that moment by any of login methodmethods.
First login
There are several methods ways to login, basic most common one is Login method, accessible by path api/security/authentication/login. It accepts 3 parameters:
| Code Block |
|---|
{
"TenantDomainName": "<tenant>",
"UserNameOrEmail": "<user name or email>",
"Password": "<password>"
} |
If all sent values are correct request passes the validation server will return following response:
...
Server returns access and refresh tokens. Both tokens have expiration time and can should not be used until after 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.
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 <> call to acquire new access token using stored refresh token (explained in more details below)
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 it can be used after access token expiration time (but before refresh token expiration). It accepts following parameters:
...