API
API keys and scopes
Publishable and secret keys, and how to limit them to bins, environments and a lifetime.
Send a key as a bearer token: Authorization: Bearer <key>. Create keys in the dashboard under Settings → API keys. A key is shown once; hotcfg stores only its SHA-256 hash.
| Credential | Can | Where it belongs |
|---|---|---|
| none | Read public bins | Anywhere |
pk_live_… (Pro) | Read the organization's bins, including private ones | Inside iOS, Android and web apps |
sk_live_… | Read and write: publish, promote, roll back, manage bins | Servers and CI only |
| dashboard session | What the user's role allows | The browser |
Only administrators create keys. Publishable keys read private bins, which are part of Pro: on Free every bin is public and read without a key, so creating one answers 403 read_only_keys_require_pro. Publishable keys made on Pro keep working after a downgrade.
A bin in another organization is reported as 404, never 403, so its existence isn't revealed.
Limiting a key
On Pro, when you create a key you can limit it to:
- some bins (up to 100),
- some environments, for example only
stagingfor CI. A key withoutproductioncan't publish, promote to, roll back, unpublish or delete production: give one to a teammate or a CI job that should only reach development and staging, - a lifetime: an expiry date, after which it answers
401 key_expired.
A limited key works only within its bins and environments (promoting needs both environments). It can't manage keys, create or delete bins, change bin settings or delete environments. A key that expires can't manage keys either, so it can't create or rotate one that outlives it. Outside its limits it gets 403 key_scope_denied.
Limits are fixed when the key is created. To change them, create a new key and revoke the old one. On Free, creating a limited key answers 403 scoped_keys_require_pro; limited keys made on Pro keep working after a downgrade.
Rotating and revoking
Rotate replaces a key's secret and keeps its name, role and limits; the old secret stops working at once. Whoever rotates a key now holds its secret, so the key becomes theirs. Revoke ends a key for good.
A secret key acts for the administrator who created (or last rotated) it:
- Removing a member from the organization revokes their keys.
- Demoting an administrator to member keeps their keys working in development and staging, but they can no longer change production or manage keys:
403 key_creator_not_admin. - Keys created before keys were tied to a person can still list, rename and revoke keys, but not create or rotate them (
403 key_unattributed). Create and rotate keys from the dashboard instead.
Last updated 10 November 2026