Core concepts

This page is the map. Skim it once; refer back to it when a term in the rest of the docs is unfamiliar.

The hierarchy

Organization                    your company / tenant
  └── Project                   one per product or service
        ├── Environment         production, staging, dev, ...
        │     └── API key       SDK credential, scoped to this env
        ├── Feature flag        the named decision
        │     └── Variation     a value the flag can return
        ├── Segment             reusable group of users
        └── Context kind        user, organization, device, ...

A flag lives at the project level: same key, same variations, same value type in every environment. State (on/off, targeting rules, individual targets, defaults) lives at the environment level. Editing the flag in development never affects production.

The vocabulary

Feature flag. A named decision point in your code that resolves to one of a fixed set of values. A flag has a key (checkout-v2), a value type (boolean, string, number, or json), and two or more variations.

Variation. A value the flag can return. A boolean flag has exactly two; a string or JSON flag can have more.

Environment. A deployment stage: production, staging, dev. Each environment holds its own configuration for every flag.

Context. What feat evaluates against. The SDK passes a context to every evaluation, like { targetingKey: "user-123", user: { plan: "pro" } }. A context can describe a user, an organization, a device, or several at once.

Context kind. The type of a context. user is built in. You can create custom kinds (organization, device) per project.

Targeting rule. An ordered rule on a flag, in one environment, that says “for contexts matching X, serve Y.” First match wins.

Individual target. A direct override that says “for this exact user, serve this variation.” Evaluated before targeting rules.

Percentage rollout. A rule outcome that splits traffic across variations by weight (10% true, 90% false). Bucketing is stable: the same user always gets the same variation while the weights are unchanged.

Segment. A named group of contexts you define once and reference from many flags. A segment can have its own rules; a flag rule can require the context to be in or not in a segment.

API key. The SDK credential. Three types: server (secret), mobile (secret, limited surface), client-side ID (public, browser-safe). Each key is scoped to one environment.

Datafile. The JSON snapshot of an environment that SDKs pull and evaluate against in process. See the datafile format for the wire shape.

How an evaluation works

When your code calls getBooleanValue("checkout-v2", false, context):

The SDK looks up the flag in the datafile.
If the flag is archived, or targeting is off, it returns the off-variation.
Otherwise it checks individual targets for an exact (kind, key) match.
Otherwise it walks the targeting rules in order; the first one whose conditions all match decides the result. The result is either a fixed variation or a percentage rollout.
Otherwise it serves the environment’s default rule (a single variation or another percentage rollout).
If anything fails (flag missing, malformed datafile), it returns the default value you passed and reports reason: ERROR.

The full chain is in Evaluation order.

What lives where

Some surfaces are turned off by default per organization and need to be enabled by an admin. See Organization features for the full list. The ones you will run into:

Feature	Off by default	Lives under
Individual targeting	yes	Flag detail in an environment
Segments	yes	Project sidebar
Scheduled changes	yes	Flag detail in an environment
Change requests / approvals	yes	Per environment, then per flag change
Workflows	yes	Flag detail in an environment
Progressive rollouts	yes	Targeting rule context menu
Audit log	always on	Project sidebar

Where to go next

Feature flags for what a flag is in detail.
Targeting rules for the rule engine.
Contexts for how to model who is asking.
Quickstart if you skipped it.