Authentication

Every call carries an API key, sent as a bearer token:

Create a key

1. In the console, open Settings › Access › API keys and choose Create key.
2. Give it a name, a role and a lifetime: 30, 90 or 365 days.
3. Copy the key. It is shown once; the console cannot show it again.

Creating and revoking keys needs the api_keys:manage permission, which Owners and Admins have.

What a key can do

• One workspace. A key stands in the workspace it was created in.
• One role. It can do what its role can do, and never more than the person who created it can do now. You can only give a key a role whose permissions you hold yourself.
• Never manage keys or people. No key can list, create or revoke API keys, whatever its role.
• Always expires. Every key has a lifetime, and an expired key is refused.

When a key is refused

When the Authorization header is present it is the whole of the authentication: a console session cookie sent beside it is ignored.

Call from a server, not a browser

The API does not allow the Authorization header from another site's page, so a key cannot be used from JavaScript running in a browser. Keep the key in a server, a script or a CI secret.

The audit log

Creating and revoking a key are recorded in the workspace's audit log. Its use is recorded too, at most once every 15 minutes for each key.