---
title: Authentication
description: Bearer keys, what each type may reach, and how to handle them.
---

Every request carries an API key as a bearer token.

```
Authorization: Bearer sk_live_your_key_here
```

No other scheme is accepted. A missing or malformed header is
`missing_api_key`; a key we do not recognise, or one that has been
revoked, is `invalid_api_key`. Both return `401`.

## Which key to use where

| | Secret (`sk_`) | Publishable (`pk_`) |
|---|---|---|
| Lives on | Your server | Anywhere, including page source |
| Can reach | The whole API | `POST /v1/subscribe` only |
| Origin restricted | No | Optionally, and you should |

A publishable key on any other endpoint is refused with
`publishable_key_not_allowed` and `403`, even though the key is valid.
That is the point of it.

See [test and live keys](/guide/test-and-live) for the environment
half of this.

## Origin restrictions

A publishable key can name the domains allowed to use it. A request
from anywhere else is refused with `origin_not_allowed`.

Set this on every publishable key you create. It costs nothing and it
turns a key someone copied out of your page source into one that only
works from your own site.

## Brand scoping

A key can be locked to one brand. Calls through it only see that
brand's topics and lists, and naming another brand's topic is refused
with `topic_not_on_key_brand`.

Worth doing if you run several brands from one workspace: a mistake
then touches one of them rather than all of them.

## Handling keys

We show a secret key once, at creation, and store only a hash. If you
lose it we cannot recover it, and you will need a new one.

- Keep them in environment variables or a secret manager, never in
  source control
- Rotate by creating the new key, deploying, then revoking the old one;
  both work during the overlap
- Revoke immediately if one leaks. Revocation takes effect on the next
  request

If a key is revoked, every request using it starts failing with
`invalid_api_key`. There is no grace period, which is the behaviour you
want from a revoke.