Skip to main content

API Authentication: 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.

There are two ways to fetch it:

# fetch the token
treasury token create
# 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.

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

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" https://admin.cordialapis.com/v1/users

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.

Except for hardened machines making programmatic use of Cordial APIs, it is preferable to use access tokens.

Create API Key​

First, set an environment variable to your organization's name, which will look similar to organizations/w2rqPdi8pjBCDRFXmWftMv:

ORGANIZATION_NAME=$(treasury admin organizations list | jq -r .name)
echo ${ORGANIZATION_NAME}

If the output contains more than one name, set the environment variable to the appropriate one.

Then, run the following command:

API_KEY=$(treasury admin api-keys create \
  --description "my API key" \
  ${ORGANIZATION_NAME} \
  | jq -r .api_key)

echo ${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