How FeatureGate works

FeatureGate separates the place where people configure flags from the path applications use to evaluate them. This keeps organisation management and billing away from runtime credentials while letting SDKs evaluate quickly from an environment snapshot.

Use this page when deciding where a resource belongs or diagnosing why a caller cannot see a flag. The hierarchy determines access, isolation, configuration, and credential scope.

Resource model

1. Account
2. Organisation
3. Project
4. Environment
5. Flag configuration
6. Evaluation key

• An account represents one person and can belong to several organisations.
• An organisation owns projects, members, roles, billing, settings, tags, and activity.
• A project is an isolation boundary for related flags and environments.
• An environment is a runtime boundary such as development, staging, or production.
• A flag defines a stable key and type. Each environment configuration supplies its fallback, ordered targeting rules, client-exposure setting, and emergency state.
• An evaluation key is bound to one project environment. It cannot choose a different environment at request time.

The same flag key can have different configurations in development and production. Those are not copies of the flag. They are environment configurations attached to one typed definition.

Decision	Resource to use
Separate billing, members, or audit ownership	Organisation
Separate applications or flag namespaces	Project
Separate deployed runtime boundaries	Environment
Separate typed decisions in application code	Flag
Separate server or browser access	Evaluation key

Configuration flow

1. Console or Management API
2. FeatureGate control plane
3. Environment snapshot
4. SDK or Evaluate API
5. Application decision

The console and Management API change control-plane state. Server SDKs fetch a snapshot and evaluate locally. Direct HTTP callers send requested flag keys and context to /v1/evaluate. A browser caller can receive only flags explicitly exposed to clients.

Changes are not deployments. A snapshot SDK observes them on its next successful refresh; direct HTTP evaluation observes current hosted configuration. Existing in-memory values can survive a temporary refresh failure.

Evaluation precedence

For a configured flag, FeatureGate checks an active emergency override first. It then evaluates ordered rule groups and returns the first matching outcome. If no group matches, it returns the environment fallback.

If the flag cannot produce a valid value, the caller receives its explicit default. Causes include a missing or archived flag, missing environment configuration, client exposure restrictions, or a type mismatch.

The caller default is application policy. Choose a value that keeps the application safe when FeatureGate is unavailable or configuration is incomplete.

Control plane and runtime responsibilities

Owners, admins, and members change project configuration according to their permissions. Management automation uses a separate key family and a deliberately narrow preview API.

Runtime callers never choose organisations, projects, or environments in the request. Their key already provides that binding. A caller cannot escape into another boundary by changing a URL parameter.

FeatureGate records privacy-safe hosted usage aggregates. It does not record raw evaluation context, targeting values, user identifiers, or resolved flag values as runtime telemetry. Local SDK checks do not leave the application process.

Common modelling mistakes

• Do not create an organisation for each deployment stage. Use environments.
• Do not use projects as folders when the flags must be evaluated together.
• Do not use flags as authorization or entitlement enforcement.
• Do not send server runtime keys to browsers.
• Do not assume creating a flag configures every environment.
• Do not treat a configuration change as proof that every process refreshed successfully.

Continue with the Quickstart, or learn how to choose organisation, project, and environment boundaries.