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.

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

​
Prerequisites

To get started with Experiment Center, you need:
  • An Auth0 development tenant
  • A Machine-to-Machine application with the following Management API scopes: 
    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 endpoint.
  • The response includes a feature_flag_id value, you need the value in the subsequent steps.
  • The feature flag starts in draft status.

​
Add two variations

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

​
Create the control variation

The control variation has empty overrides. It represents the unchanged baseline. To add a control variation, make a POST call to the /api/v2/experimentation/feature-flags/{feature_flag_id}/variations endpoint.
The response includes a variation_id value for the control. You will need it when setting up allocations.

​
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 endpoint and configure the overrides object.
Example
    "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 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 endpoint. This example creates a segment that matches mobile users in the United States:
Example
    "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" }
        ]
      }
    ]
The response includes a segment_id value. Segments apply only when you use the segment allocation strategy in the experiment.

​
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 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.
Example
    "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 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 endpoint. The experiment’s started_at value is set on first activation and does not change if you pause and reactivate.
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.

​
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. The 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.
  • 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.
The event includes experiment metadata in the details.experiment object. The variation_id field tells you which variation the user was assigned to.
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)

​
Learn more