API keys
Tracking keys and read keys: what each one can do and how to handle them.
Two kinds of key
There are two, and the difference is the whole security story: one is meant to be public, the other is a secret. Both live under your site's Settings → API.
| Key | Looks like | Can |
|---|---|---|
| Tracking key | oa_pk_… | Write events from a browser. Public by design: it goes into your HTML and can never read anything. |
| Read key | Shown once at creation | Read the site and its analytics over the read API. A secret: server-side code and scripts only, never a web page. |
A read key is shown once
Handle read keys well
One key per consumer
Create a separate key for each thing that reads (one for the cron job, one for the internal dashboard), so revoking one never breaks another.
Rotate without downtime
Rotating is create-new, move your consumer over, then revoke-old, with both keys alive during the move. Revoking on its own is immediate.
Watch the journal
Every key's credential events, created, first used, first used from a new source, revoked, are journalled and visible to the account owner, so you can always answer who could read this site.
When not to use a key
Interactive or agent-shaped? Use OAuth