# How FeatureGate works

Understand the resource model and how configuration reaches an application.

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

<FlowDiagram
  ariaLabel="FeatureGate resource hierarchy"
  items={[
    "Account",
    "Organisation",
    "Project",
    "Environment",
    "Flag configuration",
    "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

<FlowDiagram
  ariaLabel="Configuration delivery flow"
  items={[
    "Console or Management API",
    "FeatureGate control plane",
    "Environment snapshot",
    "SDK or Evaluate API",
    "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.

> [!WARNING] Flags are not authorization
> A flag may shape an experience, but it must not replace application
> authorization, entitlement enforcement, or validation of sensitive operations.

Continue with the [Quickstart](/docs/quickstart), or learn how to choose [organisation](/docs/platform/organisations),
[project](/docs/platform/projects), and [environment](/docs/platform/environments) boundaries.