> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Entities Details

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

export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
  const stageTextMap = {
    "beta": "Beta",
    "ea": "Early Access"
  };
  const stageText = stageTextMap[stage] || "a product release stage";
  const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages";
  const linkify = (text, url) => {
    return <a href={url} target="_blank" rel="noreferrer" class="link">{text}</a>;
  };
  const includeDetails = (plans, contact, terms) => {
    const hasDetails = terms || plans || contact;
    if (!hasDetails) return null;
    return <span data-as="p">
            {plans && <>This feature is available for {linkify(`${plans} plans`, "https://auth0.com/pricing")}. </>}
            {contact && "To participate, contact " + contact + ". "}
            {terms && <>By using this feature, you agree to the applicable Free Trial terms in Okta's {linkify("Master Subscription Agreement", "https://www.okta.com/legal")}.</>}
        </span>;
  };
  return <Warning>
            <span data-as="p">
                <strong>The {feature} feature is in {linkify(stageText, prsLink)}.</strong>
            </span>

            {includeDetails(plans, contact, terms)}
        </Warning>;
};

<ReleaseStageNotice feature="Auth0 Experiment Center" stage="beta" terms="true" contact="Auth0 Support" />

With the Auth0 [Management API](/docs/api/management/v2), you can define Experiment Center entity details, including properties, lifecycle states, and validation rules.

<Warning>
  During Beta, Experiment Center runs on development tenants only. Production tenants are not supported.
</Warning>

## 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`](/docs/api/management/v2/experimentation/update-experiment-status) endpoint.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Transitioning from `completed → active` is not allowed. If you need to run the same test again, create a new experiment.
</Callout>

### 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`](/docs/api/management/v2/experimentation/validate-experiment) 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`](/docs/api/management/v2/experimentation/update-feature-flag-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.

```text wrap lines theme={null}
draft → active   (requires ≥2 variations)
draft → archived
active → archived (terminal; no way back)
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Transitioning from `archived → active` is not allowed. If you archive a flag and need to run another test, create a new feature flag.
</Callout>

### 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.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Parameters use **structured mode only**. Each parameter has a named key and a typed value.
</Callout>

## 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

<CardGroup cols={2}>
  <Card title="Experiment Center Quickstart" icon="gear" href="/docs/customize/experiment-center/quickstart">
    Walk through creating a feature flag, variations, and an experiment end to end.
  </Card>

  <Card title="ACUL Integration" icon="puzzle-piece" href="/docs/customize/experiment-center/integrations/acul-integration-guide">
    Read experiment context inside Auth0 Custom Universal Login (ACUL) screens.
  </Card>
</CardGroup>