Open in ChatGPT Claude Perplexity

Authentication

Two things authenticate against the OpenAttribution API: API keys, for everyday telemetry reads and writes, and user sessions, for creating organisations and managing identity. They are not interchangeable.

API keys

Authenticated endpoints take an API key in the X-API-Key header:

bash

curl -H "X-API-Key: oat_pub_..." https://api.openattribution.org/content-owners/summary

Key prefixes

Prefix	Key type	Who uses it
`oat_pub_`	Content owner	A content owner reading its own telemetry. Bound to that owner's verified domains - a key for `example.com` only sees data for that domain. With `telemetry:write` scope it can also report events for those domains (e.g. a self-hosted edge worker or origin middleware).
`oat_pk_`	Platform / agent	Any platform org - agents, content marketplaces, affiliate and ad networks, attribution vendors, analytics tools. Used both for writing telemetry events and for reading data content owners delegate to it. The prefix is the org type, not the scope.

Scopes

What a key can do is set by its scopes, independent of the prefix:

telemetry:write - report events and sessions (POST /events, /sessions/* on telemetry.openattribution.org).
telemetry:read - query telemetry data (/content-owners/*, /agent/* on api.openattribution.org). For delegated reads, also pass delegated_from with the grantor's org id.

A request that uses a key without the required scope, or asks for data the key is not bound to, gets a 403. A missing or unrecognised key gets a 401. See Troubleshooting.

Where keys come from

API keys are minted from /api-keys in the dashboard, once your org exists. The raw key is shown once at creation - copy it then; OA only stores a hash. If you lose a key, create a new one and revoke the old.

Manifest keys are something else

A .well-known/openattribution.json manifest can carry a keys array with an Ed25519 publicKey for signing. Those are unrelated to API keys - manifest keys are about verifying signed telemetry, API keys are about authenticating HTTP requests.

Sessions vs API keys

Some operations are only available to a logged-in user, never to an API key:

Creating an organisation (POST /api/v1/identity/organizations) needs a user session. Org-scoped API keys cannot create new principals.
Submitting a platform or agent access request, and the rest of the identity surface under api.openattribution.org/api/v1/identity/*, is session-authed.

User accounts and sessions are operator-specific. On the OA-operated service you sign in with a magic link or Google OAuth; a competing operator would run its own auth stack against the same API. When calling identity endpoints outside the website, pass the session token as Authorization: Bearer {session-id}.

Rule of thumb

If the call reports or reads telemetry, use an API key. If it creates or administers an organisation, use a user session.

Control plane

Organisation, membership, domain, delegation, and settings operations live under https://api.openattribution.org/api/v1/identity/*. This is the only privileged interface for those operations - the website is just one consumer of it, with no privileges a third-party UI or CLI could not also have. The full endpoint list is in the API reference.