Authentication

Every protected REST endpoint requires a bearer access token in the Authorization header:

Authorization: Bearer <access_token>

There is no X-API-Key header and a cf_live_ API key is never sent directly as a bearer token — it’s exchanged for a short-lived access token first. That exchange step is the part every existing internal client (including our own smoke-test scripts) gets slightly wrong by doing it once and never refreshing, so it’s worth reading closely.

Two ways in

API KeysThe path for your own backend, scripts, and server-side integrations.

OAuthThe path for third-party integrations connecting on a user's behalf (Zapier today).

Both paths ultimately produce the same kind of thing: a bearer access token you attach to every request. The difference is how you get one and how long it lasts.

	API key exchange	OAuth
Who it’s for	You, calling your own account’s API	A third-party app connecting on a user’s behalf
Token prefix	cf_live_ (the key itself)	cfo_ (the minted access token)
Lifetime	Access token: 1 hour, no refresh — re-exchange the key	Access token: 1 hour, with a refresh token (90 days)
Where scopes come from	Chosen when the key is created	Chosen by the user during consent, bounded by what the client app requested

Scopes

Every access token — from either path — carries one or more scopes that gate what it can do. See Scopes for the full list and what each one unlocks.

Tokens expire — build the refresh in from day one

An API-key-derived access token lives for exactly 3600 seconds with no refresh token. There is nothing to renew — you re-exchange your API key for a new one when the old one is close to expiring (or on a 401). If you’re building anything longer-lived than a one-off script, wrap the exchange in a small client that does this automatically; see the example in API Keys.