Get started

# Concepts

Bins, environments, versions, organizations and keys.

## Bins

A **bin** is one JSON document with an id such as `mobile-flags`, unique within its organization. Its URL is `/v1/<organization slug>/<bin id>`, for example `https://api.hotcfg.run/v1/acme/mobile-flags`.

A bin is **public** (anyone can read it, and the edge caches it) or **private** (reads need a key; Pro only). Either way, only your organization can change it.

## Environments

Every bin has three environments: `development`, `staging` and `production`. Reads default to `production`. Test a change in staging, then [promote](https://hotcfg.run/docs/guides/environments) that exact version to production.

## Versions

Every publish to an environment creates the next **version** (v1, v2, …). Versions are immutable and keep their author, so you can diff, pin or roll back to any of them. A rollback publishes an old version again as a new one: history is never rewritten. Your plan sets how many versions each environment keeps.

## Schemas

A bin can have a [JSON Schema](https://hotcfg.run/docs/guides/schemas). Every publish, promote and rollback is checked against it, and a payload that doesn't match is refused.

## Organizations

Bins belong to an organization. Its members and API keys can reach only its bins. You can belong to several organizations and switch between them in the dashboard. See [Organizations and team](https://hotcfg.run/docs/account/organizations).

## Keys

| Key | Can | Where it belongs |
| --- | --- | --- |
| none | Read public bins | Anywhere |
| `pk_live_…` (publishable, Pro) | Read the organization's bins, including private ones | Inside iOS, Android and web apps |
| `sk_live_…` (secret) | Read and write: publish, promote, roll back, manage bins | Servers and CI only |

Either kind can be limited to some bins and environments, and can expire. See [API keys and scopes](https://hotcfg.run/docs/reference/keys).

Last updated 10 November 2026
