Multi-environment feature flag configuration
Last updated November 14, 2026
Environments
Flaggr supports separate flag configurations per environment, letting you safely promote changes from development through staging to production.
Default Environments
Every project starts with three environments:
| Environment | Purpose |
|---|---|
development | Local development and testing |
staging | Pre-production validation |
production | Live user-facing environment |
How It Works
Each flag can have different values and targeting rules per environment. When evaluating a flag, the SDK specifies which environment to target. Python and Go use the OpenFeature OFREP providers, which name the environment in an X-Environment header:
import { createFlaggr } from '@flaggr/sdk'
const client = createFlaggr({
serviceId: 'web-app',
apiKey: process.env.FLAGGR_TOKEN,
environment: 'production', // Target production flags
})Default Environment
Always name the environment. When an evaluation request leaves it out, the default depends on the endpoint:
| Request without an environment | Evaluates |
|---|---|
@flaggr/sdk (it calls https://api.flaggr.dev unless you set apiUrl), and POST /api/flags/evaluate or /api/flags/evaluate/batch on api.flaggr.dev | production |
Connect evaluation on flaggr.dev (POST /api/connect/evaluate, /api/connect/bulk-evaluate) | production |
Connect and gRPC-Web on api.flaggr.dev (/flaggr.v1.*) | production |
OFREP without an X-Environment header | development |
POST /api/flags/evaluate or /api/flags/evaluate/batch on flaggr.dev | development |
gRPC-Web on flaggr.dev (/api/grpc-web) | development |
Environment-Specific Configuration
Flag Values
A flag can have different enabled states and default values per environment:
| Property | Development | Staging | Production |
|---|---|---|---|
| Enabled | true | true | false |
| Default value | true | true | false |
| Rollout | 100% | 100% | 5% (progressive) |
Targeting Rules
Each environment can have its own targeting rules:
production:
- Beta users: 100%
- Internal team: 100%
- All users: 5% (progressive rollout)
staging:
- All users: 100%
development:
- All users: 100%
Environment-Specific Overrides
You can set identity overrides per environment. This is useful for:
- Enabling a flag for QA testers in staging without affecting development
- Pinning specific users to a variant in production for testing
- Giving internal teams early access in production while the flag is off for everyone else
Per-Environment API Tokens
Create a token for each environment to enforce access control. A token whose scopes name one environment (environment:<slug>:<permission>) covers the requests that name that environment, in every service. Create it with POST /api/projects/{id}/tokens and a body with "tokenType": "opaque" and scopes, from a signed-in dashboard session or an admin-tier connector (API tokens and personal access tokens can't create tokens). The environment's slug must exist in the project:
curl -s -X POST https://flaggr.dev/api/projects/proj-1/tokens \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON' | jq
{
"name": "Production reader",
"tokenType": "opaque",
"scopes": ["environment:production:read"]
}
JSONThe token doesn't expire unless you send an expiresAt. For an application's SDK, add "evaluationOnly": true: the key then only evaluates flags, and it still covers only the environment it names. A token made with permissions instead of scopes covers every environment of the project.
Recommended token strategy:
| Environment | Scopes | Use Case |
|---|---|---|
development | environment:development:write | Local development, can modify flags |
staging | environment:staging:read | CI/CD pipelines, integration tests |
production | environment:production:read (an SDK key) | Application SDKs |
| CI/CD sync | one environment:<name>:write for each environment it writes to, plus environment:<name>:read for each environment it exports from (the IaC promotion script exports from staging). The promote endpoint (POST /api/projects/{id}/environments/{slug}/promote) needs project:<id>:write. | Automated flag promotion (see IaC guide) |
See API Tokens for token types and management.
Protected Environments
Set settings.protectedEnvironment and settings.requireApproval on an environment to require approval for every change to its flags. Edits, toggles and rollbacks to a version open a change request (202); creates, deletes, bulk and import items, RUM optimization, site guardrail mitigation and bandit reallocation are refused (409 APPROVAL_REQUIRED), and the circuit breaker restores nothing there. To add a flag to a protected environment, create it in another environment and promote it — promotion opens a change request. Deleting a service whose flags are in a protected environment is refused (409 APPROVAL_REQUIRED, with environments), and DELETE /api/cleanup skips such flags and services (listed in skipped). An experiment serves its variants in every environment its flag exists in, so creating, starting or resuming an experiment, changing its variants, traffic allocation or hash config, and applying an adaptive allocation are refused (409 APPROVAL_REQUIRED) while any of those environments is protected. Experiments can't go through a change request yet. The check fails closed: if the environment can't be read, the change is refused with 503 APPROVAL_CHECK_UNAVAILABLE.
Promoting Changes Between Environments
Manual Promotion
A typical workflow:
- Create and test the flag in
development - Enable the flag in
stagingfor validation - Gradually roll out in
production(5% > 25% > 50% > 100%) - Clean up: remove the flag once fully rolled out
Automated Promotion via Export/Import
Use the export/import API to programmatically promote flag configurations:
# 1. Export flags from staging
curl -s "/api/flags/export?projectId=proj-123&environment=staging" \
-H "Authorization: Bearer fgr_staging_token" \
-o staging-flags.json
# 2. Transform for production (flags start disabled for safety)
jq '.flags |= map(.environment = "production" | .enabled = false)' \
staging-flags.json > production-flags.json
# 3. Dry run to validate
jq '{flags: .flags, conflictResolution: "skip", dryRun: true}' production-flags.json |
curl -X POST /api/flags/import \
-H "Authorization: Bearer fgr_prod_token" \
-H "Content-Type: application/json" \
--data-binary @-
# 4. Apply
jq '{flags: .flags, conflictResolution: "skip", dryRun: false}' production-flags.json |
curl -X POST /api/flags/import \
-H "Authorization: Bearer fgr_prod_token" \
-H "Content-Type: application/json" \
--data-binary @-The jq step sets enabled: false, so imported flags arrive switched off and you can enable them in production on your own schedule, using progressive rollouts for safety. Import keeps whatever enabled the file carries (true or false; left out or null, false). The promote endpoint (POST /api/projects/{id}/environments/{source}/promote) copies enabled from the source by default; leave it out of fields to keep the target's state. Promotion copies targeting without the source's rollout rules, keeps the target's, and refuses flags with a live rollout plan in the target (refused). Promotion copies onto existing flags whatever their key, but won't create a flag with a reserved key (bulk, create-from-nl, evaluate, evaluate-debug, export, import, stream) in the target (refused[] with code: FLAG_KEY_RESERVED; 409 when nothing was promoted). An import into an environment that requires approval is refused per flag (APPROVAL_REQUIRED) — promote those flags instead.
CI/CD Promotion
Automate promotion in your CI/CD pipeline. See Infrastructure as Code for GitHub Actions workflows and reusable scripts.
Environment-Specific Rollout Strategies
Different environments call for different rollout approaches:
| Environment | Strategy | Rationale |
|---|---|---|
development | 100% rollout, all flags enabled | Fast iteration, no risk |
staging | 100% rollout, match production targeting | Verify targeting rules work correctly |
production | Progressive rollout (5% → 25% → 50% → 100%) | Minimize blast radius, catch issues early |
Use progressive rollouts for production deployments with safety checks between stages.
API Usage
Create a Flag for a Specific Environment
curl -X POST /api/flags \
-H "Authorization: Bearer fgr_your_token" \
-H "Content-Type: application/json" \
-d '{
"key": "checkout-v2",
"name": "Checkout V2",
"type": "boolean",
"enabled": true,
"defaultValue": false,
"serviceId": "web-app",
"environment": "staging"
}'Evaluate in a Specific Environment
curl -X POST /api/flags/evaluate \
-H "Authorization: Bearer fgr_your_token" \
-H "Content-Type: application/json" \
-d '{
"flagKey": "checkout-v2",
"serviceId": "web-app",
"environment": "production",
"context": { "targetingKey": "user-123" }
}'List Flags by Environment
curl "/api/flags?projectId=proj-123&environment=production" \
-H "Authorization: Bearer fgr_your_token"Related
- Concepts — Data model and evaluation flow
- Import/Export — Move flags between environments
- Infrastructure as Code — Automate environment promotion
- Progressive Rollouts — Staged deployment for production
- API Tokens — Token management and scopes