API Keys

API keys are how agents and scripts authenticate to Breeth. Every key is bound to a (team, project) at mint time and inherits the role of the member who created it.

Manage keys in the dashboard at thebreeth.com/app/api-keys. The endpoints here are for advanced flows; most users mint and rotate from the UI.

Anatomy

A minted key looks like:

ck_live_thvPb4_bcggqn06xaTOYB1ueaR_ecnk0tp7Fp_IcRW8

The ck_live_ prefix identifies it as a Breeth live-mode key. The remainder is the secret. Only the hash is stored — Breeth cannot recover plaintext after creation, so save it the moment you mint it.

Scopes

Each key carries an explicit scope set:

Pick the minimum set for the use case. A read-only widget should never carry write.

Project scoping

Every key targets exactly one project. When a key writes, the resulting nodes / edges land in that project's partition and never leak. To work across multiple projects in the same team, mint one key per project.

Expiry (hackathons & trials)

Keys can carry an expires_at. After the timestamp, the key behaves like a revoked key — 401 on every call. Used by the hackathon flow to issue time-limited tokens to event participants.

Endpoints

The REST surface is read-only; mint and delete via the dashboard.

GET /v1/api_keys

List keys visible to the caller.

[
  {
    "id": "efc3abb3-77b9-4495-9e32-0acbedd5b49b",
    "name": "ingestion-bot",
    "key_prefix": "ck_live_VmbO",
    "scopes": ["write"],
    "expires_at": null,
    "created_at": "2026-05-10T03:42:11Z",
    "last_used_at": "2026-05-11T11:17:57Z",
    "revoked_at": null
  }
]

Note key_prefix only — plaintext is never returned. Use it to identify which key is which.

Best practice

• One key per integration. Don't share a single key across Claude Desktop, your CI, and your production agent. Different keys give you different revoke surfaces.
• Rotate at least annually. Mint a new key, deploy, verify, revoke the old.
• Scope tight. A monitor reading the graph should never have admin.
• Treat them like Stripe secret keys. Don't commit them; use environment variables; redact them from logs.

Revocation

Revoke a key from the dashboard. Effect is immediate — within seconds, every subsequent request with that key returns 401. Existing in-flight requests complete normally.