> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shftd2.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> An API key authenticates your account to the fragment endpoint. Your edge sends it with every card request.

An **API key** authenticates your account to the [fragment endpoint](/edge-integration). 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](https://app.shftd2.com/settings), 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.

<Warning>
  **Treat it as a secret**

  The 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.
</Warning>