Authentication

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

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 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.

Updated at, Saturday, October 10, 2026