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.

CredentialCanWhere it belongs
noneRead public binsAnywhere
pk_live_… (Pro)Read the organization's bins, including private onesInside iOS, Android and web apps
sk_live_…Read and write: publish, promote, roll back, manage binsServers and CI only
dashboard sessionWhat the user's role allowsThe 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 staging for CI. A key without production can'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