API Guide

API Credentials

In order to use the API you will have to generate an API Key Client ID and Secret either from the user interface, or by using the command line tool as described in “creating api keys”.

Authentication and Authorization

All API endpoints require authorization using Bearer tokens in the Authorization header. The Bearer token is a time-limited JWT token that is signed by the Envoy server. The JWT token contains the valid claims that the API key has: most importantly the permissions assigned to the API Key. If the endpoint requires a permission that the API key does not have then a 403 error is returned.

To obtain the JWT bearer token, you must first authenticate with the server using your client ID and secret with a POST request to /v1/authenticate.

POST /v1/authenticate HTTP/1.1
Accept: application/json
Content-Type: application/json

    "client_id": "[CLIENT_ID]",
    "client_secret": "[CLIENT_SECRET]"

The response will contain a JWT access_token and refresh_token. The access_token should be used as the Authorization: Bearer token for all API requests:

GET /v1/counterparties HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer [ACCESS_TOKEN]

By default the access token expires after 1 hour and the refresh token expires after 2 hours, becoming available 15 minutes before the access token expires (though these durations can all be configured).

To reauthenticate while the refresh_token is still valid, POST the refresh_token to the /v1/reauthenticate endpoint to obtain new access and refresh tokens without having to resupply the client ID and secret.

POST /v1/reauthenticate HTTP/1.1
Accept: application/json
Content-Type: application/json

    "refresh_token": "[REFRESH_TOKEN]"


The following table contains the permissions available to API keys:

users:manageCan create, edit, and delete users
users:viewCan view users registered on the node
apikeys:manageCan create apikeys and view associated secret
apikeys:viewCan view apikeys created on the node
apikeys:revokeCan revoke apikeys and delete them
counterparties:manageCan create, edit, and delete counterparties
counterparties:viewCan view counterparty details
accounts:manageCan create, edit, and delete accounts and crypto addresses
accounts:viewCan view accounts and crypto addresses
travelrule:manageCan create, accept, reject, and archive transactions and send secure envelopes
travelrule:deleteCan delete transactions and associated secure envelopes
travelrule:viewCan view travel rule transactions and secure envelopes
config:manageCan manage the configuration of the node
config:viewCan view the configuration of the node
pki:manageCan create and edit certificates and sealing keys
pki:deleteCan delete certificates and sealing keys
pki:viewCan view certificates and sealing keys