Skip to main content

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:

EnvironmentPurpose
developmentLocal development and testing
stagingPre-production validation
productionLive 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 environmentEvaluates
@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.devproduction
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 headerdevelopment
POST /api/flags/evaluate or /api/flags/evaluate/batch on flaggr.devdevelopment
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:

PropertyDevelopmentStagingProduction
Enabledtruetruefalse
Default valuetruetruefalse
Rollout100%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"]
}
JSON

The 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:

EnvironmentScopesUse Case
developmentenvironment:development:writeLocal development, can modify flags
stagingenvironment:staging:readCI/CD pipelines, integration tests
productionenvironment:production:read (an SDK key)Application SDKs
CI/CD syncone 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:

  1. Create and test the flag in development
  2. Enable the flag in staging for validation
  3. Gradually roll out in production (5% > 25% > 50% > 100%)
  4. 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 @-
Info

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:

EnvironmentStrategyRationale
development100% rollout, all flags enabledFast iteration, no risk
staging100% rollout, match production targetingVerify targeting rules work correctly
productionProgressive 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"