Issue and revoke API keys

An API key lets your server call EdgeKit on behalf of one site. Every key is pinned to exactly one site when it is issued, and the pin cannot change. A key with no site is never issued, and a key used for another site is refused.

Keys are for servers only. Browser code calls EdgeKit from an allowed origin with the site header and, once the user signs in, their EdgeKit session. It never holds a key.

You need the site write permission (the Owner and Admin roles) to issue or revoke keys. Without it, the API keys section lists the keys and offers no actions.

Issue a key

1. Open Delivery › Delivery › Sites and select the site the key is for.
2. In API keys, enter a Name that says what will hold the key, for example Paywall middleware — production. The name is the only way to tell two keys apart later. Up to 100 characters.
3. Optionally enter Expires in (days): a whole number from 1 to 3650. Leave it empty for a key that does not expire.
4. Select Can send streaming scores (streaming:write) only if the key will post your own per-user scores to POST /v1/streaming/{pipeline}. Leave it off for every other use. A key without it gets 403 on that route.
5. Select Issue key.
6. Copy the key, then select I have it.

The key starts with ek_ and is shown once. EdgeKit stores only a hash of it, so it cannot be shown again or recovered. If you lose it, issue another and revoke the lost one.

A new key works from its first request; issuing one needs no deploy.

Send the key

Send the key in either header:

curl -i https://your-tenant-host/v1/iglu/api/schemas \
  -H 'Authorization: Bearer ek_your_key'

const response = await fetch('https://your-tenant-host/v1/iglu/api/schemas', {
  headers: { 'x-api-key': process.env.EDGEKIT_API_KEY! },
});

console.log(response.status); // 200 when the key is valid

On a route that also selects a site with x-edgekit-site-id, the selected site must be the key’s site. The API reference marks which routes take a key: see the client API reference. A server SDK takes the key and the site id as options; see the @edgekitcloud/client-server reference.

Status	Code	Message	Cause
401	unauthorized	Missing API key.	No key on the request.
401	unauthorized	Invalid or missing API key.	The key is unknown, revoked or expired.
403	forbidden	This key is not pinned to the selected site.	The key belongs to another of your sites.
403	forbidden	This key does not hold streaming:write.	A streaming write with a key that lacks streaming:write.
404	not_found	Unknown site.	The selected site is unknown, disabled or not yet deployed.

Read the key list

Each row shows the key’s Name, its first characters (ek_ and six more), its Permissions (default when it holds none), its Status, how many Requests it has made, when it was Last used and when it Expires.

• active: the key works.
• revoked: someone took it out of service. It cannot be turned back on.
• expired: it passed its expiry date. It cannot be extended; issue a new key.

Rotate a key

1. Issue a new key for the same site, with the same permissions as the old one: a replacement for a streaming key needs streaming:write too.
2. Put the new key into your server’s configuration and deploy your server.
3. Revoke the old key once its Requests count stops rising. Last used shows a date only.

Revoke a key

1. Select Revoke on the key’s row.
2. Confirm with Revoke key.

The key stops working at its next request, and whatever holds it gets 401. No deploy is needed. Revoking keeps the row, with its request count and last use, so the key’s history stays visible.