Entities Details

Learn about Experiment Center entities: feature flags, variations, segments, experiments, and assignments.

With the Auth0 Management API, you can define Experiment Center entity details, including properties, lifecycle states, and validation rules.

During Beta, Experiment Center runs on development tenants only. Production tenants are not supported.

Experiment

Experiment lifecycle

Experiments have five states:

Status	Meaning
draft	Created but not running. Safe to test using query parameter overrides.
active	Running. Variant assignment and context injection are live for all auth transactions.
paused	Temporarily suspended. No new assignments. In-flight sessions keep their assigned variation.
completed	Concluded. No new assignments. Configuration retained for reference during manual promotion.
archived	Soft-deleted. Hidden from default list views. Analytics data retained.

To transition lifecycles, use the Management API /api/v2/experimentation/experiments/{id}/status endpoint.

Transitioning from completed → active is not allowed. If you need to run the same test again, create a new experiment.

The is_valid gate

Before an experiment can activate, it must pass a readiness check.

Experiment Center stores an is_valid boolean on every experiment and recalculates it on every write. This gives you immediate feedback during setup.

You can also determine readiness explicitly using the Management API /api/v2/experimentation/experiments/{id}/validate endpoint.

This returns is_valid: true/false and an errors array listing every blocker. The same check runs automatically when you attempt to activate via the status endpoint.

Validation rules checked on activation:

• Referenced feature flag is in active status
• At least one allocation exists
• All allocation variation_id values belong to the experiment’s feature flag
• Exactly one allocation has is_control: true
• Allocation weights sum to 100 (percentage strategy)
• Exactly one allocation has is_fallback: true (segment strategy)
• No other experiment is currently active for the tenant (Beta only)

Assignment

Query parameter overrides

You can force a specific assignment on any /authorize request by passing query parameters:

Parameter	Description
experiment_id	Enroll in a specific experiment
variation_id	Force a specific variation (requires experiment_id)
segment_id	Force a specific segment (requires experiment_id)

This works for experiments in any status, including draft. Use this during development to verify that both variations render correctly before activating.

Feature flag

Feature flag lifecycle

Feature flags have a stored lifecycle with three states:

Status	Meaning
draft	Created but not yet active. Cannot be referenced by an active experiment.
active	Ready for use. Required before any experiment that references this flag can activate.
archived	Terminal. No new experiments can reference this flag. Create a new flag if needed.

To transition between statuses, use the Auth0 Management API /api/v2/experimentation/feature-flags/{id}/status endpoint.

Activation gate: A feature flag cannot transition to active until it has at least two variations. This ensures every active flag has at minimum a control and one treatment before it goes live.

draft → active   (requires ≥2 variations)
draft → archived
active → archived (terminal; no way back)

Transitioning from archived → active is not allowed. If you archive a flag and need to run another test, create a new feature flag.

Variation

Parameters and overrides

Feature flag parameters define the configuration surface for your experiment. Each parameter has:

• A name (for example, show_passkey_prompt)
• A type: string, boolean, number, array, or object
• A default value (the baseline)

A variation’s overrides specifies only the parameters that differ. At runtime, Experiment Center merges the flag’s baseline with the variation’s overrides and delivers the full merged config object to ACUL, Actions, and page templates. Every parameter always has a value in config; you never need to write fallback logic.

Parameters use structured mode only. Each parameter has a named key and a typed value.

Segment

Segment rules

A segment’s rules is an array of rule objects. A request matches the segment if any rule in the array matches.

• match: all conditions must be true (AND logic)
• not_match: all conditions must be true (NOT logic)

Each condition compares an attribute against a value using an operator: contains, starts_with, ends_with, exists.

Available condition attributes

Segments can only use attributes available at /authorize transaction start:

Category	Attributes
Client	client_id
Connection	connection, connection_type
Organization	organization_id
Domain	domain
Device and browser	device_type, browser, platform, user_agent
Geographic (IP-derived)	country, region

Learn more

Experiment Center Quickstart

Walk through creating a feature flag, variations, and an experiment end to end.

ACUL Integration

Read experiment context inside Auth0 Custom Universal Login (ACUL) screens.