---
title: Flags
description: A typed configuration value or feature flag per environment, the audience its rules point at, and the record of every change.
type: tutorial
product: flags
summary: A flag, the audience its rules point at, and the audit trail behind both
updated: 2026-09-28
order: 0
---

A config flag is one typed value of an environment, decided per request instead
of at deploy time: a default, targeting rules and percentage rollouts, and an
answer for whoever asks. Three collections make it up — the flag, the audience
its rules point at, and the record of what changed.

## The three collections

<KeyValue
	items={[
		{ key: 'ConfigFlag', value: 'One typed configuration value or feature flag of an environment: a default, targeting rules and percentage rollouts.' },
		{ key: 'ConfigSegment', value: 'A reusable audience of an environment: subjects listed by id, and conditions over the evaluation context.' },
		{ key: 'ConfigChange', value: 'One committed change to a flag or segment: the audit trail, kept after the flag or segment is deleted.' },
	]}
/>

## A flag is one typed value

Every value of a flag has the same type, and there is always a default to fall
back on. The rest of the spec is how an evaluation departs from that default.

<PropertyTable
	properties={[
		{
			name: 'value_type',
			type: 'ConfigValueType',
			required: true,
			description: 'The type every value of the flag has. One of bool, string, int64, double, json.',
		},
		{
			name: 'default_value',
			type: 'value',
			required: true,
			description: 'The value when no rule matches, or when the flag is disabled.',
		},
		{
			name: 'enabled',
			type: 'bool',
			description: 'When false, every evaluation returns default_value and the rules are skipped: a kill switch. Default true.',
		},
		{
			name: 'rules',
			type: 'TargetingRule[]',
			description: 'Targeting rules, first match wins.',
		},
		{
			name: 'description',
			type: 'string',
			description: 'What the flag is for.',
		},
		{
			name: 'client_visible',
			type: 'bool',
			description: 'Whether a publishable key may evaluate it; default false, so a server-only flag never reaches a device.',
		},
	]}
/>

The flag's id is the key evaluators ask for, so it is worth choosing rather than
accepting the one the server assigns. `enabled` is what makes a rollout
reversible in one call: with the flag off, every evaluation returns the default
and the rules are not read at all.

## A segment is an audience you reuse

A ConfigSegment is a reusable audience of an environment. Flag rules refer to it
with IN_SEGMENT, so one change to the audience reaches every flag that names it.
That is the reason to have segments rather than the same conditions copied into
twenty flags: "our beta testers" becomes one object with one meaning.

A segment that a flag names cannot be deleted — the delete is refused — which is
what keeps a live rule from pointing at nothing. [Segments](/docs/flags/segments)
covers building one and changing it.

## A change is the audit trail

A ConfigChange is one committed change to a flag or segment of an environment.
It records the target, the action, the target's generation after the change, the
target's spec as it stood at that moment, and who made it. The trail outlives
the flag: a deleted flag leaves its changes behind.

[Change history](/docs/flags/changes) covers what each record holds and how to
read the trail back.

## Names and ids

<KeyValue
	items={[
		{ key: 'Flag', value: 'orgs/{org}/projects/{project}/envs/{env}/config_flags/{config_flag}', mono: true },
		{ key: 'Flag id', value: 'cfg_<cell><ulid>', mono: true },
		{ key: 'Segment', value: 'orgs/{org}/projects/{project}/envs/{env}/config_segments/{config_segment}', mono: true },
		{ key: 'Segment id', value: 'seg_<cell><ulid>', mono: true },
		{ key: 'Change', value: 'orgs/{org}/projects/{project}/envs/{env}/config_changes/{config_change}', mono: true },
		{ key: 'Change id', value: 'chg_<cell><ulid>', mono: true },
	]}
/>

All three live in one environment, and a name is a path, so the same path works
in the API, the CLI and the console.

## The scopes

- `config:read` — flags, segments, changes and the snapshot.
- `config:write` — creating, changing and deleting a flag or a segment.
- `config:evaluate` — reading values for one evaluation context, never the rules
  behind them. A publishable key may hold this scope, which is how a browser or
  a mobile app evaluates flags without holding a secret.
  [Keys and scopes](/docs/platform/keys-and-scopes) covers the two kinds of key.

<RelatedDocs
	links={[
		{
			href: '/docs/flags/quickstart',
			label: 'Quickstart',
			description: 'A segment, a flag that targets it, and an evaluation.',
		},
		{
			href: '/docs/flags/targeting',
			label: 'Targeting rules',
			description: 'Defaults, rules, percentage rollouts and the evaluation context.',
		},
		{
			href: '/docs/flags/segments',
			label: 'Segments',
			description: 'An audience listed by id, with conditions over the context.',
		},
		{
			href: '/docs/flags/changes',
			label: 'Change history',
			description: 'What every committed change records, and where it outlives the flag.',
		},
	]}
/>