Authentication

x-api-key: circa_live_6JeiZORoVyRPqYBuc3ft7kIWjlA7w25h

Key format

Keys are prefixed with either circa_live_ or circa_test_ followed by 32 characters of cryptographically random base64url, e.g. circa_live_6JeiZORoVyRPqYBuc3ft7kIWjlA7w25h.

Live vs. test keys

Choose the kind when you create the key in the Developer portal:

• Live (circa_live_…) — for production traffic. Circa stores only a SHA-256 hash and the first 18 characters (the "prefix"); the full value is returned exactly once at creation. Keep these in a secret manager.
• Test (circa_test_…) — for development. The plain key remains revealable on the API keys page so you can re-copy it any time. Same usage as live keys but billed against a separate sandbox quota.

Revocation

Revoking a key in the portal takes effect immediately. The next request with that key returns 401 Unauthorized. Revoked keys are soft-deleted so their historical logs remain visible.

Errors

A 401 is returned when the key is missing, malformed, unknown, or revoked.

{
  "statusCode": 401,
  "message": "Invalid API key"
}

Team scope: x-team-id (required)

Your API key inherits the team memberships of the user who created it. Every request must include an x-team-id header naming exactly one team that the key owner is an active member of:

x-api-key: circa_live_6JeiZORoVyRPqYBuc3ft7kIWjlA7w25h
x-team-id: 4b6f9c28-6f4e-4e7f-a36d-2ff989045d10

Where to find a team id

You can read the id off two places in app.circa.ai:

• The Team Settings → General dialog shows the active team's id with a copy button. Open it from the gear icon next to the team selector in the top navbar. (The row appears whenever your account has the developer portal enabled.)
• The Developer portal navbar's team dropdown also switches which team you're operating against — switch teams there to grab a different id from Team Settings.

Omitting the header returns 400 Bad Request. Passing a team the owner is not a member of returns 403 Forbidden.

{
  "statusCode": 400,
  "message": "Missing required 'x-team-id' header. Pass the id of a team the API key owner belongs to."
}

{
  "statusCode": 403,
  "message": "The API key owner is not a member of team '...'."
}

Best practices

• Store keys in a secret manager (AWS Secrets Manager, Doppler, Vercel env vars). Never commit them to source control.
• Create one key per environment (production, staging, CI) so you can revoke independently.
• Rotate keys periodically. Revoke unused keys.
• Treat keys like passwords — a leaked key gives full access to your data and can debit your credit balance via /datapoints/pull.