Create feature flags
Feature flags, also called feature toggles, permission toggles, or flags, let you turn certain functionality on and off without deploying code. They give you full control over the lifecycle of a feature. With feature flags, you can:
- Release code without exposing it to users by keeping the flag off.
- Gradually roll out a feature to a portion of your user base.
- Validate functionality and performance before a full release.
Permissions required to create a flag
To create a flag in Feature Experimentation, you must have access to an environment in the project.
When a collaborator creates a flag, they are automatically assigned the Admin role for that flag.
Note
To create a flag or audience, a collaborator must have Editor or above access in at least one environment.
If your project does not use granular permissions, the collaborator must have an Editor or above project role.
Create a flag
With the Feature Experimentation API
Use the Create a New Flag endpoint.
Endpoint – POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags
Authentication – Include your API key in the Authorization header as a Bearer token. See Generate tokens and use the REST APIs.
Request example
Replace placeholder text written in all caps with underscores with your information.
curl --request POST \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'authorization: Bearer TOKEN' \
--data '
{
"outlier_filtering_enabled": BOOLEAN_VALUE,
"description": "FLAG_DESCRIPTION",
"key": "FLAG_KEY",
"name": "FLAG_NAME"
}
'Response example
{
"key": "doc-test-flag",
"name": "Doc test flag",
"description": "Flag created via the API",
"url": "/projects/PROJECT_ID/flags/doc-test-flag",
"update_url": "/projects/PROJECT_ID/flags",
"delete_url": "/projects/PROJECT_ID/flags/doc-test-flag",
"archive_url": "/projects/PROJECT_ID/flags/archived",
"variable_definitions": {},
"environments": {
"production": {
"key": "production",
"name": "Production",
"enabled": false,
"has_restricted_permissions": true,
"priority": 1,
"rules_summary": {},
"rules_detail": [],
"id": ENVIRONMENT_ID,
"enable_url": "/projects/PROJECT_ID/flags/doc-test-flag/environments/production/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
},
"development": {
"key": "development",
"name": "Development",
"enabled": false,
"has_restricted_permissions": false,
"priority": 2,
"rules_summary": {},
"rules_detail": [],
"id": ENVIRONMENT_ID,
"enable_url": "/projects/PROJECT_ID/flags/doc-test-flag/environments/development/ruleset/enabled",
"created_time": "2025-04-14T19:48:26.000000Z"
}
},
"id": ID,
"urn": "flags.flags.optimizely.com::ID",
"archived": false,
"outlier_filtering_enabled": true,
"project_id": PROJECT_ID,
"created_by_user_id": "[email protected]",
"created_by_user_email": "[email protected]",
"account_id": ACCOUNT_ID,
"role": "admin",
"created_time": "2025-09-12T16:16:10.260857Z",
"updated_time": "2025-09-12T16:16:10.260859Z",
"revision": 1
}See the Create a New Flag endpoint reference for the full list of parameters. You can also follow the REST API cookbook and see step one to create a flag.
With the Feature Experimentation UI
See Create a flag in the user documentation for a step-by-step guide.
Implement the feature flag
Before implementing the flag, decide how to pass user identifiers to Feature Experimentation. This ensures each user has a consistent experience of the flag being on or off.
See Handle user IDs for information.
After you create the flag in the Feature Experimentation dashboard, you need to integrate it with your application code. Use the Decide method to enable or disable the flag for a user.
// Decide if user sees a feature flag variation
var user = optimizely.CreateUserContext("user123", new UserAttributes { { "logged_in", true } });
var decision = user.Decide("flag_1");
var enabled = decision.Enabled;// Decide if user sees a feature flag variation
user := optimizely.CreateUserContext("user123", map[string]interface{}{"logged_in": true})
decision := user.Decide("flag_1", nil)
enabled := decision.Enabled// Decide if user sees a feature flag variation
var user = await flutterSDK.createUserContext(userId: "user123");
var decisionResponse = await user!.decide("flag_1");
var decision = decisionResponse.decision;
var enabled = decision!.enabled;// Decide if user sees a feature flag variation
OptimizelyUserContext user = optimizely.createUserContext("user123", new HashMap<String, Object>() { { put("logged_in", true); } });
OptimizelyDecision decision = user.decide("flag_1");
Boolean enabled = decision.getEnabled();// Decide if user sees a feature flag variation
const user = optimizely.createUserContext('user123', { logged_in: true });
const decision = user.decide('flag_1');
const enabled = decision.enabled;// Decide if user sees a feature flag variation
$user = $optimizely->createUserContext('user123', ['logged_in' => true]);
$decision = $user->decide('flag_1');
$enabled = $decision->getEnabled();# Decide if user sees a feature flag variation
user = optimizely.create_user_context("user123", {"logged_in": True})
decision = user.decide("flag_1")
enabled = decision.enabled// Decide if user sees a feature flag variation
var [decision] = useDecision('flag_1', { overrideUserAttributes: { logged_in: true }});
var enabled = decision.enabled;# Decide if user sees a feature flag variation
user = optimizely_client.create_user_context('user123', {'logged_in' => true})
decision = user.decide('flag_1')
enabled = decision.enabled// Decide if user sees a feature flag variation
let user = optimizely.createUserContext(userId: "user123", attributes: ["logged_in":true])
let decision = user.decide(key: "flag_1")
let enabled = decision.enabledFor more detailed examples of each SDK, see the following:
- JavaScript SDK example usage – SDK versions 6.0.0 and later.
- JavaScript (Browser) SDK example usage – SDK versions 5.3.5 and earlier.
- JavaScript (Node) SDK example usage – SDK versions 5.3.5 and earlier.
Adapt the integration code in your application. Show or hide the flag's functionality for a given user ID based on the boolean value your application receives.
The Decide method separates code deployment from the decision to show a feature. The flag's rules determine the result. For example, it returns false if the user is assigned to the control or "off" variation in an experiment.
Next steps
To deliver feature flag configurations, see Create flag variations.