Authorization type configuration for the REST API access

The Waves Enterprise blockchain platform supports the following two types of authorization for the node’s REST API access:

  • api-key string hash authorization;

  • authorization via the authorization service.

The authorization type is specified in the REST API configuration section of the node configuration file. api-key string hash authorization type is a simple method of the access management to a node with a low level security. If the api-key hash is leaking out to the attacker, he is getting the full access to the node. When you utilize the separate authorization service with access tokens, you increase the security level of your blockchain network to the high level. You can read more information about the authorization service in the Authorization service section.

rest-api section of the node configuration file

The rest-api section allows to bound the node network address to the REST API interface, to choose and configure the authorization type, also to specify the limits for some REST API methods.

# Node's REST API settings
rest-api {
# Enable/disable REST API
enable = yes

# Network address to bind to
bind-address = "127.0.0.1"

# Port to listen to REST API requests
port = 6862

# Authorization strategy should be either 'oauth2' or 'api-key', default is 'api-key'
auth {
  type = "api-key"

  # Hash of API key string
  api-key-hash = "H6nsiifwYKYEx6YzYD7woP1XCn72RVvx6tC1zjjLXqsu"

  # Hash of API key string for PrivacyApi routes
  privacy-api-key-hash = "H6nsiifwYKYEx6YzYD7woP1XCn72RVvx6tC1zjjLXqsu"
}
# For OAuth2:
# auth {
#   type: "oauth2"

#   # OAuth2 service public key to verify auth tokens
#   public-key: "AuthorizationServicePublicKeyInBase64"
# }

# Enable/disable CORS support
cors = yes

# Enable/disable X-API-Key from different host
api-key-different-host = no

# Max number of transactions
# returned by /transactions/address/{address}/limit/{limit}
transactions-by-address-limit = 10000
distribution-address-limit = 1000
}

Parameters description

  • enable - REST API option activation.

  • bind-address - a network address to bind the REST API interface.

  • port - a port to listen to REST API requests.

  • cors - enable/disable CORS support.

  • transactions-by-address-limit - a maximum number of transactions returned by /transactions/address/{address}/limit/{limit} method.

  • distribution-address-limit - GET ​/assets​/{assetId}​/distribution​/{height}​/limit​/{limit}.

auth section for the api-key type

  • auth-type - the authorization type, specify the api-key value - the string hash authorization.

  • api-key-hash- a hash of API key string.

  • privacy-api-key-hash - a hash of API key string for privacy methods.

auth section for the oauth2 type

  • auth-type - the authorization type, specify the oauth2 value - the token authorization.

  • public-key - a public key of the authorization service.

When you use the key string hash for the authorization

Specify the api-key value for the auth-type parameter. Create the api-key-hash for the REST API access by using the generators-x.x.x.jar utility. To run the utility, you need to specify the api-key-hash.conf file as one of the parameters, which defines the parameters of creating the api-key-hash. Use the following command to run the generator:

java -jar generators-x.x.x.jar ApiKeyHash api-key-hash.conf

Specify the value obtained as a result of the utility execution in the parameter api-key-hash in the node configuration file.

Create the privacy-api-key-hash by the same way as the api-key-hash to get the privacy methods access. Specify the value obtained as a result of the utility execution in the parameter privacy-api-key-hash in the node configuration file.

When you use the token authorization

Specify the oauth2 value for the auth-type parameter, write the public key of the authorization service into the public-key parameter.