Multi-environment feature flag configuration

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:

await initializeFlaggr({
  mode: 'remote',
  apiUrl: 'https://flaggr.dev',
  serviceId: 'web-app',
  apiKey: 'flg_your_token',
  environment: 'production',  // Target production flags
})

Default Environment

If no environment is specified in an evaluation request, Flaggr uses development as the default. Always specify the environment explicitly in staging and production deployments.

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 separate API tokens for each environment to enforce access control:

# Create a production-only token
curl -X POST /api/tokens \
  -H "Authorization: Bearer flg_admin_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production SDK Token",
    "tokenType": "jwt",
    "permissions": { "read": true, "write": false, "delete": false },
    "scopes": ["service:web-app:read"]
  }'

Recommended token strategy:

Environment	Token Permissions	Use Case
`development`	read + write	Local development, can modify flags
`staging`	read only	CI/CD pipelines, integration tests
`production`	read only	Application SDKs
CI/CD sync	read + write	Automated flag promotion (see IaC guide)

See API Tokens for token types and management.

Promoting Changes Between Environments

Manual Promotion

A typical workflow:

Create and test the flag in development
Enable the flag in staging for 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 flg_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
curl -X POST /api/flags/import \
  -H "Authorization: Bearer flg_prod_token" \
  -H "Content-Type: application/json" \
  -d "$(jq '{flags: .flags, conflictResolution: "skip", dryRun: true}' production-flags.json)"
 
# 4. Apply
curl -X POST /api/flags/import \
  -H "Authorization: Bearer flg_prod_token" \
  -H "Content-Type: application/json" \
  -d "$(jq '{flags: .flags, conflictResolution: "skip", dryRun: false}' production-flags.json)"

Info

Promoted flags are created with enabled: false by default. This lets you review and enable them in production on your own schedule, using progressive rollouts for safety.

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 flg_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 flg_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 flg_your_token"

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

Next→