Feature flags let you ship code behind a switch and control who sees it — roll a feature out to a percentage of users, target specific accounts, or kill it instantly without a deploy. Flags are environment-scoped, so a flag can be on in development and off in production.

## Model

A flag has a stable `key` (unique per environment), a `type` (`boolean`, `string`, `number`, or `json`), and a `defaultValue`. Evaluation returns the default unless a **targeting rule** matches the subject.

Rules evaluate in ascending `priority`; the first match wins and supplies its `value`. A rule matches when:

- its `conditions` all hold for the subject — `userId`, `orgId`, and/or an `attributes` map (every listed attribute must equal the subject's), and
- the subject falls inside the rule's `percentageRollout` bucket (0–100; blank means 100%). Bucketing is deterministic per `key` + subject, so a given user stays in or out across evaluations.

## Evaluate from your app

Evaluation is a public endpoint authenticated with an environment API secret (`adenv_…`). Send the subject and, optionally, the specific keys you care about:

```bash
curl -X POST https://api.authdog.com/feature-flags/v1/evaluate \
  -H "Authorization: Bearer $AUTHDOG_ENV_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "subject": { "userId": "user_123", "attributes": { "plan": "pro" } } }'
# → { "flags": { "new-dashboard": true, "max-seats": 25 } }
```

Pass `"keys": ["new-dashboard"]` to evaluate a subset. Evaluate on your backend and treat the result as the source of truth; client-side flags are UX hints, not access control.

## Manage flags

Flags are managed with your Authdog management API token at
`/v1/tenants/{tenantId}/environments/{environmentId}/feature-flags`:

| Operation | Endpoint |
| --- | --- |
| List | `GET /feature-flags` |
| Create / update | `POST /feature-flags` |
| Delete | `DELETE /feature-flags/{id}` |

Create and update are one upsert (by `id`, or by env + `key` on create). Supplying a `rules` array **replaces** the flag's rule set, so send the full intended set each time.

```json
{
  "key": "new-dashboard",
  "name": "New dashboard",
  "type": "boolean",
  "defaultValue": false,
  "rules": [
    { "priority": 0, "conditions": { "userId": "user_123" }, "value": true },
    { "priority": 1, "conditions": {}, "percentageRollout": 25, "value": true }
  ]
}
```

Prefer managing flags in the **Feature flags** console module, which provides the same list, editor, and targeting-rule builder.

## Guidance

- Keep keys stable; code references them by key.
- Clean up flags once a rollout is complete — archive or delete flags you no longer read.
- Percentage rollout is sticky per subject; ramp by raising the percentage over time.
- Don't put secrets in flag values; use [Vault](/docs/vault) for credentials.

## Related

- [Actions](/docs/actions)
- [Vault](/docs/vault)
- [Backend requests](/docs/backend)