Open in ChatGPT Claude Perplexity

Authentication

API keys authenticate telemetry and supported organisation-scoped identity operations. User sessions authenticate sign-up, membership management and operator administration. Each endpoint determines which credentials it accepts.

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.
identity:read - read organisation-scoped identity resources, including domains, keys and delegations.
identity:write - write supported identity resources. This does not unlock session-only or administrator endpoints.
partner:provision - provision organisations as an enabled trusted platform partner; also requires identity:write. See partner access.

Omitting scopes or sending scopes: null when creating a key requests telemetry:read, telemetry:write, identity:read. Defaults exclude identity write and partner provisioning. An explicit empty array grants no permissions. The returned scopes are the effective permissions; missing scope metadata must not be treated as unrestricted. Choose custom scopes in the dashboard for explicit identity write or a smaller permission set.

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/content-telemetry.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. The separately gated partner provisioning endpoints are an exception.
Submitting platform or agent access requests, listing your organisations, claiming invites and managing members require a user session. Operator admin endpoints additionally require an allowlisted administrator session.

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

Use an API key for telemetry and supported organisation-scoped identity automation. Use a session for user-specific actions. Provisioning with a key needs both identity write and partner provisioning permission; a normal session does not bypass that gate.

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.