Authorization service REST API methods

You can read more about working with REST API in this section. The authorization service REST API methods are accessed via HTTPS protocol. Methods are closed by authorization and are marked with the

lock
icon.

Ways of authorization

Depending on a used authorization method different values for access to the node REST API are set.

../_images/authTypes.png

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

  • ApiKey or PrivacyApiKey (apiKey) - api-key-hash value for shared access to the node REST API, as well as for access to the privacy methods.

Api-key-hash authorization

Generation of an api-key-hash query is set during the node configuration. The value of the rest-api.api-key-hash field can be also obtained with the use of the /utils/hash/secure method of the node REST API. In order to sign queries with a node keystore key, set a keystore password in the password field of the POST /transaction/sign query.

Query example:

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'

Token authorization

If the authorization service is used, the client receives a pair of tokens, refresh and access for access to the node. Tokens can be obtained via the REST API of the authorization service.

The POST ​/v1​/user method is used for registration of the user. Following parameters are passed to the input:

  • login - user login (e-mail). A user e-mail is used as a login.

  • password - account password.

  • locale - language of e-mails. Possible variants: en and ru.

  • source - user type. Possible variants: license and voting.

A user receives tokens only after registration.

In order to obtain and update tokens, following methods are used:

  1. POST ​/v1​/auth​/login - obtaining of an authorization token with the use of login and password. This method is used for authorization of users.

  2. POST ​/v1​/auth​/token - obtaining of refresh and access authorization tokens for services and applications. The method does not require parameters, and in reply sends token values. The method can be used only by administrators of authorization service.

  3. POST ​/v1​/auth​/refresh - updating of the refresh token. Token value is passed for input.

Authorization service methods

GET ​/status

Getting the authorization service status.

Method answer

{
 "status": "string",
 "version": "string",
 "commit": "string"
}

POST ​/v1​/user

Registering a new user.

Method request

{
  "username": "string",
  "password": "string",
  "locale": "string",
  "source": "string"
 }

If the registration was successful, the response code is 201. Otherwise, the registration have failed.

GET ​/v1​/user​/profile
lock

Getting user data.

Method answer

{
 "id": "string",
 "name": "string",
 "locale": "en",
 "addresses": [
 "string"
 ],
 "roles": [
 "string"
 ]
 }

POST ​/v1​/user​/address
lock

Getting an user address.

Method request

{
  "address": "string",
  "type": "string"
 }

Method answer

{
  "addressId": "string"
 }

GET /v1​/user​/address​/exists

Checking the user’s email address. The method accepts the user’s email address as an input parameter.

Method answer

{
   "exist": true
 }

POST ​/v1​/user​/password​/restore

Restoring an user account password.

Method request

{
  "email": "string",
  "source": "string"
 }

Method answer

{
  "email": "string"
 }

POST ​/v1​/user​/password​/reset

Reseting an user password.

Method request

{
  "token": "string",
  "password": "string"
 }

Method answer

{
  "userId": "string"
 }

GET ​/v1​/user​/confirm​/{code}

Entering a confirmation code to reset an user account password. The value of the confirmation code is passed to the method as input.

POST ​/v1​/user​/resendEmail

Resending a password recovery code to the specified email address.

Method request

{
   "email": "string",
   "source": "string"
}

Method answer

{
   "email": "string"
}

POST ​/v1​/auth​/login

Registering a new user in the authorization service.

Method request

{
  "username": "string",
  "password": "string",
  "locale": "string",
  "source": "string"
 }

Method answer

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "string"
 }

POST ​/v1​/auth​/token
lock

Registering external services and applications in the authorization service. This method does not require any request parameters.

Method answer

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "string"
 }

POST ​/v1​/auth​/refresh

Getting a new refresh token.

Method request

{
  "token": "string"
 }

Method answer

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "string"
 }

GET​ /v1​/auth​/publicKey

Getting the authorization service public key.

Method answer

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA7d9Oj/ZQTkkjf4UuMfUu
QIFDTYxYf6QBKMVJnq/wXyPYYkV8HVFYFizCaEciv3CXmBH77sXnuTlrEtvK7zHB
KvV870HmZuazjIgZVSkOnOY7F8UUVNXnlzVD1dPsOGJ6orM41DnC1W65mCrP3bjn
fV4RbmykN/lk7McA6EsMcLEGbKkFhmeq2Nk4hn2CQvoTkupJUnOCP1dhO4bq1lQ7
Ffj9K/FJq73wSXDoH+qqdRG9sfrtgrhtJHerruhv3456e0zyAcDO8+sJUQFKY80B
SZMEndVzFS2ub9Q8e7BfcNxTmQPM4PhHO5wuTqL32qt3uJBx2OI4lu3OND44ZrDJ
BbVog73oPjRYXj+kTbwUZI66SP4aLcQ8sypQyLwqKk5DtLRozSN0OIrupJJ/pwZs
9zPEggL91T0rirbEhGlf5U8/6XN8GVXX4iMk2fD8FHLFJuXCD7Oj4JC2iWfFDC6a
uUkwUfqfjJB8BzIHkncoqOZbpidEE2lTWl+svuEu/wyP5rNlyMiE/e/fZQqM2+o0
cH5Qow6HH35BrloCSZciutUcd1U7YPqESJ5tryy1xn9bsMb+On1ocZTtvec/ow4M
RmnJwm0j1nd+cc19OKLG5/boeA+2zqWu0jCbWR9c0oCmgbhuqZCHaHTBEAKDWcsC
VRz5qD6FPpePpTQDb6ss3bkCAwEAAQ==
-----END PUBLIC KEY-----