Authentication

API keys

An API key (cak_live_...) is how you call ConvoStack from your own backend, script, or CI job — anywhere that isn't a logged-in browser session.

Generating a key

1. Log into the dashboard.
2. Settings → API Keys → Generate new key.
3. Give it a name (e.g. "production backend", "nightly sync job") — this is just for your own reference in the list view.
4. Copy the raw key immediately. It is shown once. ConvoStack stores only a one-way hash of it — if you navigate away without copying it, there is no way to recover it. Revoke it and generate a new one instead.

curl -X POST https://convostack.ai/api/settings/api-keys \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "production backend"}'

{
  "id": "11111111-2222-3333-4444-555555555555",
  "name": "production backend",
  "keyPrefix": "cak_live_ab12cd34",
  "createdAt": "2026-07-21T12:39:11.133Z",
  "rawKey": "cak_live_ab12cd34ef56gh78ij90kl12mn34op56qr78st90uv12wx34yz56ab78cd90ef"
}

rawKey is the only field you'll ever see the full key on. Every other response (list, etc.) shows only keyPrefix — enough to identify which key is which, never enough to reconstruct or reuse it.

Note: key generation and revocation themselves require a logged-in session, not an API key. A key can never be used to mint or revoke another key — that would let a leaked key regenerate its own replacement.

Using a key

Every request, regardless of endpoint:

curl https://convostack.ai/api/agents \
  -H "Authorization: Bearer cak_live_..."

What a key can access

A key is scoped to the organization that created it — nothing more, nothing less. It behaves exactly like a logged-in session for that org:

• Same data visibility (agents, calls, conversations, credits — all filtered to that org)
• Same credit balance and plan limits
• Same rate limits

It cannot:

• See or affect any other organization's data
• Change the billing plan, update the payment method, or perform any other account-level action — those require a real login session
• Mint or revoke API keys (see above)

Revoking a key

curl -X DELETE https://convostack.ai/api/settings/api-keys/11111111-2222-3333-4444-555555555555 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Revocation is immediate. The next request made with that key returns 401, whether it's already in flight from a script you forgot about or a key that just leaked.

Listing your keys

curl https://convostack.ai/api/settings/api-keys \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Returns every active key for your org — prefix, name, creation date, and last-used timestamp. Revoked keys are excluded entirely rather than returned with a revoked flag. Never the raw key itself.

Rotating a key

There's no in-place "rotate" endpoint — rotation is generate-new, switch-over, then revoke-old:

1. Generate a new key.
2. Update whatever holds the old one (env var, secrets manager, CI variable).
3. Confirm the new key works.
4. Revoke the old one.

Keeping the old key alive until step 4 avoids a deploy-time outage where the old key stops working before the new one is wired in everywhere it's used.

Security notes

• Treat an API key like a password. Anyone holding it has full access to your org's data and can spend your org's credits.
• Don't commit keys to source control. Don't log them. Don't put them in URLs or query params.
• If a key is ever exposed (committed, logged, pasted somewhere public), revoke it immediately and generate a replacement — don't wait to "see if anything bad happens."