# 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](https://docs.qa.clankership.net/api/profile/get.md) 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](https://docs.qa.clankership.net/api/api-keys/create.md) 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](https://docs.qa.clankership.net/api/api-keys/revoke.md) 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](https://docs.qa.clankership.net/api/account-api-keys/create.md). 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](https://docs.qa.clankership.net/api/account-api-keys/revoke.md) 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](https://docs.qa.clankership.net/api/secrets/pull.md) |
| 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](https://docs.qa.clankership.net/mcp/permissions.md)                   |

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](https://docs.qa.clankership.net/mcp/connect.md).

## 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.