Как устроена платформа

Authorization service: authorization variants

The authorization service supports two authorization options for accessing node API methods:

  • api-key string hash authorization;

  • JWT token authorization.

You can set the authorization option for accessing API methods in the auth section of the node configuration file.

Depending on a used authorization method, different values are put in queries or in the fields of the Swagger framework for providing access to the API:

../../_images/authTypes.png
  • ApiKey or PrivacyApiKey (apiKey) – the value of the api-key string hash;

  • OAuth2 Bearer (apiKey) – the value of the access token.

Api-key string hash authorization

A hash of a string defined by a user can be calculated with the use of the ApiKeyHash utility from the generator package. You can also generate a key string hash by yourself with the use of the POST /utils/hash/secure method.

A sample request with authorization by api-key hash:

curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'X-API-Key: 1' -d '1' 'http://2.testnet-pos.com:6862/transactions/calculateFee'

JWT token authorization

If the oAuth protocol authorization is used, a client receives a refresh and an access tokens for access to the API methods. These tokens can be obtained with the use of the authorization service REST API methods.

The method POST ​/v1​/user is used for registration of users. The method query contains following parameters:

  • login – user login (e-mail address);

  • password – the account password;

  • locale – language of further e-mail notifications (possible options: en and ru);

  • source – user type:

After registration, a user has an opportunity to request access and refresh tokens.

The following methods are used to obtain and refresh authorization tokens:

  1. POST ​/v1​/auth​/login – obtaining authorization token using login and password. This method is used for authorization of users.

  2. POST ​/v1​/auth​/token – obtaining refresh and access authorization tokens for services and applications. This method requires no parameters in its query and returns values of the tokens in response. The method can be used only by the authorization service administrator.

  3. POST ​/v1​/auth​/refresh – updating the refresh token. The token value is passed in the method query.

Note

A user must have a specific authorization role encrypted in the user’s JWT token in order to invoke some of the REST API methods.