Authentication

Authenticate API requests with a user or account API key, sent as a bearer token or in the X-API-Key header.

Every API request carries an API key. A user API key acts as you; an account API key acts for a workspace with the role it was given. Both start with ctk_, and both are shown only once, when you create them.

Send the key

Send the key in either header:

bash

curl https://api.clankertest.com/v1/me \
  -H "Authorization: Bearer ctk_…"

curl https://api.clankertest.com/v1/me \
  -H "X-API-Key: ctk_…"

A request without a key, or with a revoked or unknown one, fails with 401 Unauthorized:

json

{ "message": "An API key is required", "_tag": "Unauthorized" }

Get your profile tells you who a key acts for. For an account API key it returns the key itself, with accountWorkspaceId and accountRole.

User API keys

A user API key acts as you, with your current role in each workspace you belong to. If your role changes, the key's access changes with it; if you leave a workspace, the key loses it.

Create one on the website under Settings › Security › API keys with Create API key, or with Create an API key using a key you already have.
You can have up to 20 active keys. Names are 1–80 characters, such as CI deploys.
After creation, the API shows only the key's first 8 and last 4 characters, and when it was last used. Revoke an API key when you no longer need it; its next request fails with 401.

Account API keys

An account API key belongs to one workspace instead of a person, so automation keeps working when people come and go. It acts with the role it was given, with the same permissions as a person in that role.

Owners and admins create them under Settings › Security › Account API keys, or with Create an account API key. Only owners create or manage keys with the owner role.
An account API key sees only its own workspace. Another workspace's paths return 404.
Changing its role keeps its value. Revoke an account API key ends it at once.

Some actions belong to a person, so an account API key cannot take them: changing a profile or notification preferences, listing or creating user API keys, creating a workspace, registering an agent, sending a ticket to an agent, and commenting on a ticket. Those fail with 403 Forbidden.

Which key to use

Caller	Use
A script you run yourself	A user API key
CI and other shared automation	An account API key with the lowest role that works, usually member
A deployment pulling production secrets	A vault key (`ctvk_…`); see Pull an environment's secrets
The `clanker` CLI	`clanker auth login`, or `CLANKER_API_KEY` set to a user or account API key
A coding agent	MCP with an agent grant; see Permissions

Neither kind of API key reads production secret values: production values reach a deployment only through a pull with a vault key. Vault keys work only on that pull endpoint, and only for the products and production environments they name.

CLI logins

clanker auth login signs the CLI in with a device code you approve in the browser. The CLI then sends its own access token (ctat_…) as a bearer token, which the API accepts like your user API key. Access tokens last 15 minutes and the CLI refreshes them for up to 30 days. Revoke a login under Settings › Security › CLI logins, or with clanker auth logout.

Agents use OAuth, not API keys

Coding agents connect to the MCP server at https://api.clankertest.com/agent/mcp and to the agent HTTP API at /agent/v1 with an agent access token from OAuth. Those tokens work only there: the /v1 API answers them with 401. API keys, in turn, do not work on /agent/mcp or /agent/v1. See Connect a client.

What stays on the website

Signing up, signing in with Google or a password, and resetting a password happen only on the website. They are not API endpoints. Keep keys out of source control and URLs: store them in your CI's or platform's secret store.