Skip to content
Context docs

API keys

Create a task API key, choose read or write, keep it out of your code and rotate it.

The Evals API and CLI authenticate with a task API key, the app’s general-purpose API key. A key belongs to the person who created it and to their organization, and it can never do more than its owner can do in the app.

Read and write

CapabilityLabel in the appWhat it allows
evals:readRead evalsEvery HTTP endpoint, and every CLI command that only reads, except listing workflows (evals targets workflow, and --workflow on evals monitors list), which needs evals:write.
evals:writeChange evalsCreate, edit and delete datasets, tasks, criteria, evaluations and scorecards, and start and stop runs.

A key for a dashboard or a report needs only evals:read. Give evals:write only to a key that builds or runs evaluations, such as a CI job. Only the key’s owner can grant evals:write, because the model calls its runs make are charged to them; an admin creating a key for someone else can’t include it.

Create a key

  1. In the app, open Settings > API > Task keys and choose New key.
  2. Name the key after where it will be used, for example ci-nightly-evals.
  3. Leave Agent scope set to Any allowed agent. A key scoped to one agent can’t read Evals data, except traces, which it reads for its own agents only.
  4. Check the capabilities it needs. New keys start with most capabilities checked; for a read-only key, clear everything except Read evals.
  5. Optionally set Expires. A key with no expiry works until it is revoked.
  6. Choose Create key and copy the key. It is shown only once, and it starts with tsk_.

Send the key

Over HTTP, send it in either header. The CLI reads it from CONTEXT_API_KEY.

Authorization: Bearer <task-api-key>
X-API-Key: <task-api-key>

Keep it secret

  • Store the key in an environment variable or your secret manager, never in source code or a repository.
  • Use one key per system, so you can revoke one without breaking the others.
  • If a key leaks, revoke it at once.

Rotate a key

The app has no rotate button. Rotate in three steps, which keep the old key working until the new one is in place:

  1. Create a new key with the same capabilities.
  2. Deploy the new key to every system that uses the old one, and check that requests succeed.
  3. Revoke the old key: open it in Settings > API > Task keys and choose Revoke key.

After you revoke a key, requests with it get 401. For up to 60 seconds after you revoke it, a request that is also over the rate limit may get 429 rather than 401.

A key can’t read another organization’s data: the organization comes from the key, never from the request. If the owner loses Evals access, so does the key.