# Provision flags through automation

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

1. Call [`GET /v1/organisations`](/docs/api/reference/management/organisations/list).
2. Select the organisation by stable ID rather than display position.
3. Call [`GET /v1/projects`](/docs/api/reference/management/projects/list).
4. Select the project and retain its stable ID.
5. 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.

```sh
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:

```sh
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:

1. Re-read the current flag definition.
2. Re-list environments.
3. Skip matching configurations.
4. Apply only missing or intentionally changed fallbacks.
5. 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.

Related pages: [Management API overview](/docs/automation/management-api),
[Configure flags across environments](/docs/flags/environment-configuration), and
[Production integration checklist](/docs/evaluate/production-checklist).