Skip to main content
The API has two authentication schemes. Which one an endpoint uses depends on who is meant to call it. One endpoint needs neither: POST /auth/sso-discovery, which the sign-in page calls before anyone is signed in.

​
Tracing keys

A tracing key identifies a project, not a person. Everything sent with it lands in that project, and the key can do nothing except send telemetry: it can’t read traces or call any other endpoint.

​
Format

The prefix records whether you created the key as Live or Test in Settings → Tracing keys. Both prefixes are accepted by every ingestion endpoint and behave identically; the distinction is for your own bookkeeping.

​
Sending the key

Rules:
  • If the Authorization header starts with Bearer (capital B, one space), the rest of it is used as the key and x-tracing-key is ignored.
  • Otherwise x-tracing-key is used. An Authorization header with any other scheme, or a lowercase bearer, is ignored.
  • Surrounding whitespace is trimmed.

​
How a key is checked

  1. The key must match tk_live_ or tk_test_ followed by exactly 48 hex characters. Anything else is rejected with 401 “Invalid tracing key format.” before any lookup.
  2. AgentHub hashes the key with SHA-256 and looks the hash up. Only hashes are stored, which is why a key can be shown only once, at creation.
  3. A revoked key is rejected with 401 “Invalid or revoked tracing key.” Revocation takes effect on the next request.
  4. If the hash doesn’t match, AgentHub falls back to each project’s built-in legacy key, which is generated when the project is created. That key isn’t shown in the UI and can’t be revoked under Settings → Tracing keys; it’s accepted only so early integrations keep working. Always use a key from Settings → Tracing keys for new work.

​
Managing keys

Creating and revoking keys needs the manage_org_settings permission (Owner and Admin roles). Any member of the organization can list a project’s keys, but the list shows only the prefix and a short hint, never the full key. See Tracing keys for the UI, or the Tracing keys endpoints in this reference.
Never put a tracing key in browser or mobile code. Anyone who can read the key can write traces into your project. Send telemetry from your servers.

​
Session authentication

All other endpoints act as the signed-in user. They read the session cookie set when that user signed in to AgentHub or ModelHub with a password or through Okta SSO, and they see exactly what that user can see in the web app.
  • There are no personal API tokens or service accounts. These endpoints are designed for the web apps; calling them from a script means reusing a browser session, which isn’t supported.
  • An expired or missing session returns 401. Most endpoints use the code UNAUTHORIZED; the chat and encryption-key endpoints use UNAUTHENTICATED.
  • The organization is always derived from the session’s own memberships, never trusted from the request. Project-scoped endpoints look the project up through your memberships, so a project in another organization returns 404 PROJECT_NOT_FOUND rather than revealing that it exists.
  • Being signed in but not a member of the organization returns 403 FORBIDDEN “You do not have access to this organization.”

​
Permissions

Each organization has four system roles. Their permissions are: Your organization’s super admins act with the full Owner permission set in every organization they can reach, whatever their role there. For what each role means in the product, see Roles and permissions. A request that lacks the permission it needs returns 403 FORBIDDEN.

​
Required permission per endpoint

“Member” means any role in the endpoint’s organization. “A or B” means either permission is enough.
Reading traces checks organization membership, not the view_traces permission. Every role has view_traces, so this makes no practical difference today.