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:

CLI

treasury admin api-keys list

Curl

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.

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

Create API Key

Create an API key by running the following.

CLI

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

Curl

# see your organizations
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" https://admin.cordialapis.com/v1/organizations

You can also determine your organization name by browsing https://admin.cordialapis.com/organizations manually.

ORGANIZATION_NAME="<your-organization-name>"
curl -X POST \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    --data '{
        "description": "my API key",
        "organization": "'"${ORGANIZATION_NAME}"'"
    }' \
  https://admin.cordialapis.com/v1/api-keys

HTTPie

# see your organizations
http -A bearer -a ${ACCESS_TOKEN} https://admin.cordialapis.com/v1/organizations

ORGANIZATION_NAME="<your-organization-name>"
http -A bearer -a ${ACCESS_TOKEN} \
  https://admin.cordialapis.com/v1/api-keys \
  description="my API key" \
  organization="${ORGANIZATION_NAME}"

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

CLI

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.

Curl

curl -u ${API_KEY} https://admin.cordialapis.com/v1/users

HTTPie

http -A basic -a ${API_KEY} https://admin.cordialapis.com/v1/users

List API keys

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

CLI

treasury admin api-keys list

Curl

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

HTTPie

http -A bearer -a ${ACCESS_TOKEN} https://admin.cordialapis.com/v1/api-keys

Delete API key

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

treasury admin api-keys delete 1qZ45fy89rwcDoxhHsUSvj