Feature flags

A small key/value flag store with an optional per-tenant override layer. Platform admins manage flags; any signed-in user can read the resolved set for their own organization.

Resolution rule: a per-tenant row (one whose organization_id matches the caller's org) wins over the global default (organization_id: null) for the same flag_key.

::: tip Auth

• GET /v1/admin/feature-flags — platform Viewer or higher.
• PUT /v1/admin/feature-flags — platform Admin or higher.
• GET /v1/feature-flags — any authenticated user (cookie or Bearer). :::

---

GET /v1/admin/feature-flags

List global flags and, optionally, one tenant's override rows.

Request

GET /v1/admin/feature-flags?organization_id=<uuid>

Query param	Type	Notes
organization_id	UUID	Optional. When set, the response also includes this tenant's override rows alongside the globals.

Response

200 OK

[
  { "flag_key": "passkeys", "organization_id": null, "enabled": true, "value": null },
  { "flag_key": "beta_dashboard", "organization_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "enabled": true, "value": { "variant": "v2" } }
]

Field	Type	Meaning
flag_key	string	The flag identifier.
organization_id	UUID|null	null = global default; a UUID = per-tenant override.
enabled	bool	Whether the flag is on.
value	object|null	Optional structured payload for non-boolean flags.

---

PUT /v1/admin/feature-flags

Upsert a global or per-tenant flag.

Request

PUT /v1/admin/feature-flags

{
  "flag_key": "beta_dashboard",
  "organization_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "enabled": true,
  "value": { "variant": "v2" }
}

Field	Type	Required	Notes
flag_key	string	yes	The flag to set.
organization_id	UUID	no	Omit for the global default; set for a per-tenant override.
enabled	bool	yes	On/off.
value	object	no	Optional structured payload.

Response

200 OK

Returns the upserted flag in the same shape as one GET list element.

---

GET /v1/feature-flags

The resolved flag set for the authenticated caller's organization. Any signed-in user. Per-tenant overrides are already applied — the caller never sees another tenant's rows.

Request

GET /v1/feature-flags

Response

200 OK

A map of flag_key → resolved value:

{
  "passkeys": { "enabled": true, "value": null },
  "beta_dashboard": { "enabled": true, "value": { "variant": "v2" } }
}

Field	Type	Meaning
<flag_key>.enabled	bool	Resolved on/off for this org.
<flag_key>.value	object|null	Resolved payload, if any.

---

Error responses

Status	Code	When
401	authentication_required	No valid auth credential.
403	forbidden	Caller lacks the required platform role (admin endpoints only).
403	csrf_failed	Cookie-authed PUT without a valid X-IdentSphere-CSRF header.
400	invalid_input	Malformed body.