Authentication and permissions
Send the key in x-management-key. Create and rotate keys on Management Keys. The plaintext is shown only after creation or rotation.
| Permission | Allows | Scope rules |
|---|---|---|
| CanEvaluate | POST /flags/{name} | Application scope is required. Environment scope is optional. |
| CanRead | List and retrieve flag definitions. | Application scope filters accessible flags. |
| CanWrite | Create, update, configure, and delete flags. | Includes read. Application and config-environment scopes are enforced. |
A key is 64 lowercase hex characters, shown once at creation and once again on rotation and never retrievable afterwards. Only admins can create, rotate, disable, or delete keys. Authenticated keys are cached for 60 seconds, so disabling or rotating a key takes up to a minute to stop the old value from working — roll new keys out before rotating, not after.
A key may combine permissions. Missing or invalid keys return 401; valid keys without the required permission return 403.
Evaluation API
POST /flags/{name}
Requires CanEvaluate. The request stage is required. If the key has an environment scope, the stage must match it (case-insensitive) and the key's own spelling of that stage is what config lookup uses; otherwise the key can evaluate any environment in its scoped application. An org-wide key cannot evaluate at all — evaluation always requires an application scope. Add ?explain=true to include the decision reason.
| Field | Type | Required | Purpose |
|---|---|---|---|
| userId | string | yes | Stable user identifier for targeting and deterministic rollout. |
| stage | string | yes | Environment to evaluate. |
| clientId | string | null | no | Optional client-specific configuration selector. |
| context | object | no | Free-form values consumed by targeting rules. |
Request
POST /flags/checkout-redesign?explain=true
x-management-key: $FF_MANAGEMENT_KEY
Content-Type: application/json
{
"userId": "user-42",
"stage": "production",
"clientId": "checkout-api",
"context": { "plan": "pro", "country": "DE" }
}Response (200)
{
"variant": true,
"key": "on",
"reason": {
"code": "rule_matched",
"message": "Matched rule 'pro-users'.",
"ruleId": "pro-users"
}
}Without explain=true, the reason property is omitted. Some terminal outcomes add documented metadata alongside variant and key.
Evaluation reason codes
Public Management API
These are the supported service-integration endpoints under /api/flags. Every call authenticates with a Management Key in the x-management-key header; give the key CanRead to read flags and CanEvaluate to evaluate them.
| Method | Path | Permission | Result |
|---|---|---|---|
| GET | /api/flags | CanRead | Lists visible flag definitions. |
| GET | /api/flags/{name} | CanRead | Returns one flag definition. |
| POST | /api/flags | CanWrite | Creates a flag; returns 201. |
| PUT | /api/flags/{name} | CanWrite | Partially updates flag metadata. |
| POST | /api/flags/{name}/configs | CanWrite | Upserts one stage configuration. |
| DELETE | /api/flags/{name} | CanWrite | Deletes the flag and returns 204. |
Archiving is performed with PUT /api/flags/{name} and { "isArchived": true }. There is no separate public archive endpoint.
Status codes
| 400 | Required data is missing or the body cannot be parsed. |
| 401 | The Management Key is missing, unknown, or disabled. |
| 402 | The organization requires an active subscription. |
| 403 | The key lacks the required permission or violates its application/environment scope. |
| 404 | The flag or requested evaluation target was not found. |
| 409 | A flag with the requested name already exists, a new stage configuration targets an environment the flag doesn't use, or a new dependency's parent is missing one of the flag's environments. |
| 429 | A rate limit was exceeded. Evaluation is partitioned by Management Key. |
| 500 | An unexpected server error occurred. |