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

# Experiment Center Quickstart

> Learn how to create a feature flag, add variations, create an experiment, activate it, and observe enriched experiment data in tenant logs.

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" />

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

## Prerequisites

To get started with Experiment Center, you need:

* **An Auth0 [development](/docs/get-started/tenant-settings#environment-tag) tenant**

* **A [Machine-to-Machine](/docs/get-started/apis/create-m2m-app-test#create-machine-to-machine-applications-for-testing) application** with the following Management API scopes:

  ```text wrap lines theme={null}
  read:experimentation
  create:experimentation
  update:experimentation
  delete:experimentation
  ```

## 1. Create and activate the feature flag

A feature flag defines what you are testing and the possible variations.

To create a feature flag, make a `POST` call to the [`/api/v2/experimentation/feature-flags`](/docs/api/management/v2/experimentation/create-feature-flag) endpoint.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  * The response includes a `feature_flag_id` value; you need the value in the subsequent steps.
  * The feature flag starts in `draft` status.
</Callout>

### Add two variations

The feature flag needs at least two variations before it can activate: a control and a treatment.

#### Create the control variation

You can create a control variation with the parameter `overrides` for a specific feature flag.

To add a control variation, make a `POST` call to the [`/api/v2/experimentation/feature-flags/{feature_flag_id}/variations`](/docs/api/management/v2/experimentation/create-variation) endpoint.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The response includes a `variation_id` value for the control. You will need it when setting up allocations.
</Callout>

#### Create the treatment variation

The treatment variation overrides the parameters you want to change.

To add the treatment variation, make a `POST` call to the [`/api/v2/experimentation/feature-flags/{feature_flag_id}/variations`](/docs/api/management/v2/experimentation/create-variation) endpoint and configure the `overrides` object.

```json Example theme={null}
    "overrides": {
      "show_passkey_prompt": { "value": true },
      "prompt_style": { "value": "modal" }
    }
```

### Activate the feature flag

Now that you have two variations, activate the feature flag. An experiment cannot activate unless its referenced feature flag is in `active` status.

To transition the feature flag status to `active`, make a `POST` call to the [`/api/v2/experimentation/feature-flags/{feature_flag_id}/status`](/docs/api/management/v2/experimentation/update-feature-flag-status) endpoint.

## 2. Create a segment (optional)

If you want to target specific traffic, create a segment. Skip this step if you want a simple percentage split across all traffic.

To create a segment, make a `POST` call to the [`/api/v2/experimentation/segments`](https://auth0.com/docs/api/management/v2/experimentation/create-segment) endpoint.

This example creates a segment that matches mobile users in the United States:

```json Example theme={null}
    "name": "mobile-us-users",
    "description": "Mobile users from the United States",
    "rules": [
      {
        "match_type": "all",
        "conditions": [
          { "attribute": "device_type", "operator": "equals", "value": "mobile" },
          { "attribute": "country", "operator": "equals", "value": "US" }
        ]
      }
    ]
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The response includes a `segment_id` value. Segments apply only when you use the `segment` [allocation strategy](/docs/api/management/v2/experimentation/create-experiment#body-allocation-strategy) in the experiment.
</Callout>

## 3. Create and activate an experiment

Create an experiment that references your feature flag and defines how to split traffic.

To create an experiment, make a `POST` call to the [`/api/v2/experimentation/experiments`](/docs/api/management/v2/experimentation/create-experiment#body-allocations) endpoint.

This example uses a 90/10 percentage split using the `allocations` object: 90% of users get the control, 10% get the treatment. This is a typical cautious rollout starting point.

```json Example theme={null}
    "allocations": [
      {
        "variation_id": "var_Id",
        "weight": 90,
        "is_control": true
      },
      {
        "variation_id": "var_Id",
        "weight": 10,
        "is_control": false
      }
    ]

```

The experiment starts in `draft` status with `is_valid: false`. This is expected; the full readiness check runs in the next step.

### Validate the experiment

Before activating, confirm the experiment is ready. The `/validate` endpoint returns the same checks that run on activation.

To confirm the experiment, make a `POST` call to the [`/api/v2/experimentation/experiments/{experiment_id}/validate`](/docs/api/management/v2/experimentation/validate-experiment) endpoint.

The response includes the `is_valid` value to confirm if you are ready to activate.

### Activate the experiment

When the experiment is valid and you have tested both variations, activate it.

To transition the experiment status to `active`, make a `POST` to the [`/api/v2/experimentation/experiments/{experiment_id}/status`](/docs/api/management/v2/experimentation/update-experiment-status) endpoint.

The experiment's `started_at` value is set on first activation and does not change if you pause and reactivate.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  **One active experiment per tenant.** If another experiment is already active, activation returns `400 experiment_active_limit_exceeded`. Pause or complete the other experiment first.
</Callout>

## 4. Trigger an auth event and observe results

Trigger a test login through your test tenant. For example, open a browser and navigate to your `/authorize` URL without any override parameters.

Complete the login flow. Experiment Center resolves the active experiment, assigns a variation using deterministic hashing, injects the experiment context, and enriches the resulting auth event.

### Verify enriched logs

You can review the Auth0 logs for experiment events:

* Navigate to Auth0 [**Dashboard > Monitoring > Logs**](https://manage.auth0.com/dashboard/#/logs).

* Use Log streaming: if you already stream tenant logs to an analytics tool (Datadog, Splunk, Segment, etc.), enriched experiment metadata flows through the same stream automatically.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The event includes experiment metadata in the `details.experiment` object. The `variation_id` field tells you which variation the user was assigned to.
</Callout>

<Check>
  You have successfully run your first experiment when:

  1. Your auth events in tenant logs include `details.experiment` with `experiment_id` and `variation_id`
  2. Both variations produce the correct behavior when tested with query parameter overrides
  3. The same device or user consistently gets the same `variation_id` across multiple auth events (deterministic assignment)
</Check>

## Learn more

* Read the [ACUL integration guide](/docs/customize/experiment-center/integrations/acul-integration-guide) to learn how to branch your ACUL component code on experiment context.
* Read the [Actions integration guide](/docs/customize/experiment-center/integrations/actions-integration-guide) to use `event.experiment` in post-login and registration triggers.