API keys
An API key lets a script, pipeline, or dashboard read your organization's workflows and
runs through the public API at /api/v1/public/, without signing in as a person. Each key
belongs to one organization and can only see that organization's data.
API keys need a plan that includes API access, and creating or revoking a key needs permission to update the organization's settings.
Creating a key
- Go to Settings, then Organization, then API Keys.
- Select Create Key.
- Give the key a name that says where it is used, such as
CI pipeline. - Optionally choose an expiration date. The key stops working on that date.
- Choose its scopes (see below), then select Create Key.
The full key is shown once, straight after you create it. Copy it into your secret store before closing the dialog. Coldsea keeps only a hash, so a lost key cannot be shown again; revoke it and create a new one.
If your plan does not include API access, creating a key is refused and you are pointed to billing.
Scopes
A scope decides what a key may read. Grant only the scopes an integration needs, so a leaked key exposes as little as possible. Scopes are chosen when the key is created and cannot be changed afterwards; to change them, create a new key and revoke the old one.
| Scope | What it allows |
|---|---|
workflows:read | List workflows and read their details. |
executions:read | List runs and read their status, steps, and events. |
executions:logs | Read the log output of a run. |
executions:logs is separate because log output is whatever your scripts print, which
can include values you would not want an integration to hold. A status dashboard
typically needs executions:read alone.
A request that needs a scope the key does not have is refused with a 403 response whose
detail.code is API_KEY_SCOPE_MISSING and whose detail.requiredScope names the scope.
The Scopes column on the API Keys tab shows what each key can do. Keys created before scopes were introduced show All scopes: they keep working with every scope. Replace them with scoped keys when convenient.
Using a key
Send the key in the X-API-Key header. In this example COLDSEA_API_URL holds your
Coldsea API address:
curl -H "X-API-Key: $COLDSEA_API_KEY" \
"$COLDSEA_API_URL/api/v1/public/executions/"
Revoking a key
Select the delete icon on the key's row and confirm. The key stops working immediately and cannot be restored. Revoked keys are hidden from the list; select Show revoked keys to see them.
You can still list and revoke keys after your plan loses API access, so a key can always be shut off.