Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auth0-feat-experiment-center.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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, and production end-user traffic does not flow through experiments.

​
Feature flag

The following feature flag options are available:

​
Feature flag lifecycle

Feature flags have a stored lifecycle with three states:
StatusMeaning
draftCreated but not yet active. Cannot be referenced by an active experiment.
activeReady for use. Required before any experiment that references this flag can activate.
archivedTerminal. 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)
Transition from archived → active is not allowed. If you archive a flag and need to run another test, create a new feature flag.

​
Variation

The following variation options are available:

​
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, the 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. Free-form or string-only parameter modes are not available yet.

​
Segment

The following segment options are available:

​
Segment rules

A segment’s rules is an array of rule objects. A request matches the segment if any rule in the array matches. A rule matches if its conditions satisfy the match_type:
  • match_type: "all": all conditions must be true (AND logic)
  • match_type: "any": at least one condition must be true (OR logic)
Each condition compares an attribute against a value using an operator: equals, not_equals, in, not_in, exists, not_exists.

​
Available condition attributes

Segments can only use attributes available at /authorize transaction start:
CategoryAttributes
Clientclient_id
Connectionconnection, connection_type
Organizationorganization_id
Domaindomain
Device and browserdevice_type, browser, platform, user_agent
Geographic (IP-derived)country, region

​
Experiment

The following experiment options are available:

​
Experiment lifecycle

Experiments have five states:
StatusMeaning
draftCreated but not running. Safe to test using query parameter overrides.
activeRunning. Variant assignment and context injection are live for all auth transactions.
pausedTemporarily suspended. No new assignments. In-flight sessions keep their assigned variation.
completedConcluded. No new assignments. Configuration retained for reference during manual promotion.
archivedSoft-deleted. Hidden from default list views. Analytics data retained.
To transition lifecycles use the Management API /api/v2/experimentation/experiments/{id}/status endpoint.
Transition 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. The 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

The following assignment options are available:

​
Query parameter overrides

You can force a specific assignment on any /authorize request by passing query parameters:
ParameterDescription
experiment_idEnroll in a specific experiment
variation_idForce a specific variation (requires experiment_id)
segment_idForce 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.

​
Learn more

Configure Experiment Center

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

Troubleshooting

Diagnose common Experiment Center issues during setup or rollout.