Provision flags through automation

Preview

Discover resources, create a typed flag, configure environments, and verify the result.

Provisioning a usable flag requires a typed definition and at least one environment configuration. Use a management key scoped to the intended organisation and workflow.

This recipe is appropriate for trusted deployment or platform automation. Targeting, tags, and rollout orchestration remain console workflows in the current preview.

Required scopes

The complete workflow can require:

management:organisations:read
management:projects:read
management:environments:read
management:flags:read
management:flags:write

Use a separate runtime key for verification. A management key cannot evaluate the created flag.

Discover the target

Call GET /v1/organisations.
Select the organisation by stable ID rather than display position.
Call GET /v1/projects.
Select the project and retain its stable ID.
List project environments and choose explicit keys.

Never assume the first environment is development or the last is production. Check archived state and fail when the requested environment is not active.

Idempotency and flag reconciliation

List flags before creating. Use the desired key as the idempotency identity.

If the key does not exist, create it with name, immutable type, lifecycle, intent, cleanup date, and cleanup note as required.

curl -X POST \
  "https://api.featuregate.dev/v1/projects/$FEATUREGATE_PROJECT_ID/flags" \
  -H "Authorization: Bearer $FEATUREGATE_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new-checkout",
    "name": "New checkout",
    "type": "boolean",
    "lifecycleKind": "temporary",
    "intent": "release"
  }'

If the key exists with the expected type and meaning, skip creation. If type or meaning differs, stop and require a new key. Never coerce or repurpose an existing contract.

Configure environments

For every intended active environment, send a typed fallback:

curl -X PUT \
  "https://api.featuregate.dev/v1/projects/$FEATUREGATE_PROJECT_ID/flags/new-checkout/environments/staging" \
  -H "Authorization: Bearer $FEATUREGATE_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "defaultValue": false }'

Treat each environment as a separate reconciliation step. Development may intentionally receive a different value from production.

Do not configure every environment automatically unless that is the declared policy. Missing configuration is a meaningful state and differs from a boolean fallback of false.

Handle partial failure

Track which environment operations succeeded. A run can create the definition and configure staging before production fails.

On retry:

Re-read the current flag definition.
Re-list environments.
Skip matching configurations.
Apply only missing or intentionally changed fallbacks.
Stop on a contract conflict.

Do not delete the flag as automatic rollback. It may predate the run, have active callers, or contain configuration added by a human.

Verify the result

Read the flag list and environment configuration responses. Then use a minimum-scope non-production runtime key to make a safe evaluation.

Confirm project, environment, key, type, value, and reason. Keep the runtime key separate from the management secret and out of automation logs.

Cleanup and ownership

Automation should set lifecycle metadata that points to a real owner and review. It should not create temporary release flags without a cleanup contract.

The Management API cannot currently configure targeting or tags. Complete those in the console and record a privacy-safe change note.