Skip to main content

Access Tokens and API Keys

There are two mechanisms to authenticate to Cordial APIs, one for humans, one for machines.

Access Tokens​

Manual login in your browser will set cookies on the cordial.systems and cordialapis.com subdomains.
Specifically, this cookie is a JSON Web Token (JWT), has a lifetime of 24 hours, and can be deleted on both domains via manual logout.

This allows manual access to our APIs, for instance you can browse to https://admin.cordialapis.com/v1/users.
You can also use this access token as bearer token to make programmatic requests.

To get an access token:

# fetch the token
treasury login
# set an environment variable to the token
ACCESS_TOKEN=$(treasury token get)

The first command will pop up a browser tab, and then store the token for you automatically.

You can also copy this access token from https://auth.cordial.systems/login manually.

Once you have ACCESS_TOKEN set, use it to make programmatic requests, for instance:

treasury admin api-keys list

API keys​

API keys can be created by an Organization admin, using an access token.

Whereas the access token is a bearer token, API keys are used with Basic authorization.
The API key (ID, secret) pair are used like a (username, password) pair.

Unlike access tokens, API keys are long lived and do not expire.

Create API Key​

Create an API key by running the following.

treasury admin api-keys create --description "my API key" 

The API key can be copied from the api_key field of the ApiKey resource, it may look likeV23emW7cgtsvDkTiHdKyMN:12ioqPh89ABtDEFkHXRTMN. You will note that the first part before the colon corresponds to the resource ID, and the second part after the colon corresponds to the secret field.

Use API Key​

treasury --api-key ${API_KEY} admin users list

Here, the --api-key argument overrides use of the access token.
You may verify this by deleting the latter with treasury token delete.

List API keys​

Currently, you can retrieve API key secrets after creation, this may change in the future.

treasury admin api-keys list

Delete API key​

API keys can be permanently deleted by referencing their ID or name.

treasury admin api-keys delete 1qZ45fy89rwcDoxhHsUSvj