# API keys (/docs/api-keys)



An API key authenticates the [server client](/docs/server-client) and the
[route handler](/docs/route-handler). It has full access to your files, so it
belongs **only on a server** — never in the browser, a mobile app, or client-side
code.

## Key format [#key-format]

Every key starts with the prefix `s3d_live_`, which makes keys easy to spot in
logs and configs (and easy to scan for if one leaks).

```
s3d_live_AbC123XyZ...   ← the full secret, shown once at creation
s3d_live_AbC123         ← the safe display prefix the dashboard shows afterward
```

Only a SHA-256 **hash** of the key is stored. The full secret is shown exactly
once, when you create it — copy it then. Afterward the dashboard can only show the
short display prefix, never the full key.

## Create a key [#create-a-key]

In the dashboard, open **API Keys → Create key**, give it a name (so you can tell
keys apart later), and copy the secret immediately.

Set it on your server as an environment variable:

```bash
S3DELIVERY_TOKEN=s3d_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

The SDK reads `S3DELIVERY_TOKEN` automatically:

```ts
const s3 = new S3Delivery(); // reads S3DELIVERY_TOKEN
```

Or pass it explicitly:

```ts
const s3 = new S3Delivery({ token: process.env.S3DELIVERY_TOKEN });
```

If no key is provided and `S3DELIVERY_TOKEN` is unset, the constructor throws an
[`S3DeliveryError`](/docs/errors) with code `MISSING_TOKEN`.

## How the key is sent [#how-the-key-is-sent]

The SDK sends the key on the `x-api-key` header. The API also accepts it as a
`Bearer` token on the `Authorization` header. You never set these yourself — the
client does it — but it is useful to know if you call the REST API directly.

## Rotate a key [#rotate-a-key]

To rotate without downtime:

1. Create a new key in the dashboard.
2. Update `S3DELIVERY_TOKEN` on your server and redeploy.
3. Once traffic is on the new key, revoke the old one.

Revoking takes effect immediately: any request using a revoked key is rejected as
`UNAUTHORIZED` (`401`). Revoked keys do not count toward your
[key limit](/docs/limits#api-keys).

<Callout type="warn" title="If a key leaks">
  Revoke it right away and create a replacement. Because every key carries the `s3d_live_` prefix,
  you can grep your logs, history, and repos for accidental exposure.
</Callout>

## Multiple keys [#multiple-keys]

Hold several keys (up to the [plan limit](/docs/limits#api-keys)) to separate
environments or services — for example one per deploy target — so you can rotate
or revoke each independently without affecting the others.

## Storing keys safely [#storing-keys-safely]

* Keep keys in server-side environment variables or a secrets manager, never in
  client bundles or version control.
* Do not embed a key in a browser app or mobile binary. Browser uploads go through
  your [route handler](/docs/route-handler), which keeps the key server-side.
* Scope keys per environment so a leak in one place does not compromise the rest.