Authentication API

When you run a node, you can require that API calls have an authorization token attached. This API manages the creation and revocation of authorization tokens.

An authorization token provides access to one or more API endpoints. This is useful for delegating access to a node’s APIs. Tokens expire after 12 hours.

An authorization token is provided in the header of an API call. Specifically, the header Authorization should have value Bearer TOKEN.GOES.HERE (where TOKEN.GOES.HERE is replaced with the token).

This API is only reachable if the node is started with config flag--api-auth-required. If the node is started without this CLI, API calls do not require authorization tokens, so this API is not reachable. This API never requires an authorization token to be reached.

Authorization token creation must be permissioned. If you run your node with --api-auth-required, you must also specify the file to read the Auth API's password from, with argument --api-auth-password-file. You must provide this password in order to create/revoke authorization tokens.

Format#

This API uses the json 2.0 RPC format. For more information on making JSON RPC calls, see here.

Endpoint#

/ext/auth

Methods#

auth.newToken#

Creates a new authorization token that grants access to one or more API endpoints.

Signature:

auth.newToken(
    {
        password: string,
        endpoints: []string
    }
) -> {token: string}

• password is this node’s authorization token password.
• endpoints is a list of endpoints that will be accessible using the generated token. If endpoints contains an element "*", the generated token can access any API endpoint.
• token is the authorization token.

Example Call:

curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "auth.newToken",
    "params":{
        "password":"YOUR PASSWORD GOES HERE",
        "endpoints":["/ext/bc/X", "/ext/info"]
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/auth

This call will generate an authorization token that allows access to API endpoints /ext/bc/X (that is the Value Chain) and /ext/info (that is the info API.)

Example Response:

{
  "jsonrpc": "2.0",
  "result": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJFbmRwb2ludHMiOlsiKiJdLCJleHAiOjE1OTM0NzU4OTR9.Cqo7TraN_CFN13q3ae4GRJCMgd8ZOlQwBzyC29M6Aps"
  },
  "id": 1
}

This authorization token should be included in API calls by giving header Authorization value Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJFbmRwb2ludHMiOlsiKiJdLCJleHAiOjE1OTM0NzU4OTR9.Cqo7TraN_CFN13q3ae4GRJCMgd8ZOlQwBzyC29M6Aps.

For example, to call info.peers with this token:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.peers"
}' 127.0.0.1:9650/ext/info \
-H 'content-type:application/json;' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJFbmRwb2ludHMiOlsiKiJdLCJleHAiOjE1OTM0NzU4OTR9.Cqo7TraN_CFN13q3ae4GRJCMgd8ZOlQwBzyC29M6Aps'

auth.revokeToken#

Revoke a previously generated token. The given token will no longer grant access to any endpoint. If the token is invalid, does nothing.

Signature:

auth.revokeToken(
    {
        password: string,
        token: string
    }
) -> {}

• password is this node’s authorization token password.
• token is the authorization token being revoked.

Example Call:

curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "auth.revokeToken",
    "params":{
        "password":"123",
        "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTMxNzIzMjh9.qZVNhH6AMQ_LpbXnPbTFEL6Vm5EM5FLU-VEKpYBH3k4"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/auth

Example Response:

{
  "jsonrpc": "2.0",
  "result": {},
  "id": 1
}

auth.changePassword#

Change this node’s authorization token password. Any authorization tokens created under an old password will become invalid.

Signature:

auth.changePassword(
    {
        oldPassword: string,
        newPassword: string
    }
) -> {}

• oldPassword is this node’s current authorization token password.
• newPassword is the node’s new authorization token password after this API call. Must be between 1 and 1024 characters.

Example Call:

curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "auth.changePassword",
    "params":{
        "oldPassword":"OLD PASSWORD HERE",
        "newPassword":"NEW PASSWORD HERE"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/auth

Example Response:

{
  "jsonrpc": "2.0",
  "result": {},
  "id": 1
}