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](https://hotcfg.run/docs/account/organizations#roles) 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 `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
