Skip to content
Trace API & MCP Docs

Authentication

Every /v1 endpoint requires an API key. This page covers the key classes, how to send a key, and which endpoints need a user-scoped credential.

Key classes

Section titled “Key classes”

Create and manage keys in the Trace app under Settings → API Key (personal keys) and Settings → Organization Keys (shared org keys), at https://app.tracedata.ai/settings. The full key is shown only once at creation — store it securely.

Class Prefix Bound to Use it for
User key trace_… A specific user within an org Programmatic access tied to you; the only key class that can call user-scoped endpoints (see below).
Organization key trace_org_… An org, no specific user Shared service-to-service access for a whole team. Cannot call user-scoped endpoints.

Both are validated the same way and carry the same org context. The difference that matters day-to-day: only a user key carries a specific user identity, which some endpoints require.

Sending a key

Section titled “Sending a key”

Send your key in the X-API-Key header:

Terminal window
curl https://api.tracedata.ai/v1/companies/stripe.com \
  -H "X-API-Key: trace_your_key_here"

A missing or unrecognized key returns 401; see Errors.

Endpoints that require a user-scoped key

Section titled “Endpoints that require a user-scoped key”

Most endpoints (company lookups, technology and partnership data, computations) accept any valid key — user or org. These are documented as needing “any credential.”

A subset operate on resources owned by a specific user — Lists endpoints (/v1/lists/*) are the main example. These require a credential that carries a user identity: a user key (trace_…). An org key (trace_org_…) sent to a user-scoped endpoint is rejected with 403 and the error code user_credential_required.

Endpoint group Accepted credentials
Company, technology, partnership reads User key or org key
Lists (/v1/lists/*) User key only

Security best practices

Section titled “Security best practices”
  • Keep keys server-side. Never embed a key in browser, mobile, or other client-side code where a user can read it.
  • Use the narrowest key that works. Prefer an org key for shared services and a user key only where a user identity is required.
  • Rotate on exposure. If a key leaks, create a new one and revoke the old one from Settings. Because keys are stored only as hashes, a lost key cannot be recovered — you must mint a replacement.
  • One key per integration. Separate keys make it easy to revoke a single integration without disrupting the rest, and make usage attribution clean.

Next steps

Section titled “Next steps”