An API key authenticates your account to the fragment endpoint. Your edge sends
it with every card request; a request without a valid key is rejected. You need one before you wire up
your edge.
Create a key
In the console, open Settings → API keys, give the key a name, and
create it. The full key is shown once, so copy it immediately. Afterwards only a short prefix is kept,
so the console can list your keys without ever storing the secret.
Use it on every request
Send the key with each fragment request, either way:
X-API-Key header: use this. It keeps the key out of URLs, out of access logs and out of
downstream caches.api_key query parameter: for edges that can only template a URL and cannot set a request
header, such as an ESI tag. The key then appears in the request URL, so it must never be rendered
into HTML or into any URL a visitor can see.
doubleshift verifies the key on every request and resolves your account from it:
- No key, or an unknown or revoked key →
401.
- A valid key whose account does not own the requested
fragment_id → 403.
Rotate or revoke
Keys are per account, and you can hold several. To rotate, create a new key, switch your edge to it, then
revoke the old one in Settings. Revocation rejects new requests immediately; a card already cached
against a URL that carried the old key stays available for the rest of its cache window
(s-maxage=120, then stale-while-revalidate=240). Revoke any key you suspect has been exposed.
Keys are account-scoped: there is no per-site or per-fragment scope, and no expiry: a key stays
valid until you revoke it.
Treat it as a secretThe key authenticates your whole account. Render it server-side, in an ESI tag or an edge worker, and
never expose it in client-side code or on a public page.
