# Feature Flags

Feature Flags lets you turn features on per customer, per user or for a percentage of traffic, using the same organizations and users OhAuthCat already knows.

## Define a flag

`POST /v1/feature_flags` (scope `feature_flags:write`; reads need `feature_flags:read`):

| Field         | Meaning                                                                       |
| ------------- | ----------------------------------------------------------------------------- |
| `key`, `name` | The key your code asks for, and a label                                       |
| `kind`        | `boolean` or `multivariate`                                                   |
| `variants`    | The possible values, each a `key` and a JSON `value`                          |
| `enabled`     | When off, every evaluation returns `off_variant`                              |
| `rules`       | Ordered: `conditions` on an attribute and what to `serve` when they all match |
| `fallthrough` | What to serve when no rule matches                                            |

A condition compares an attribute with `in`, `not_in`, `contains`, `starts_with`, `ends_with`, `greater_than` or `less_than`. To serve a variant, name it; for a rollout, give weights per variant and a `bucket_by` attribute. The same organization or user always lands in the same bucket.

Updates send the flag's current `revision`; if someone else changed it first, the update answers [`feature_flag_revision_stale`](/errors/feature_flag_revision_stale/) instead of overwriting. Changes emit `feature_flag.created`, `feature_flag.updated` and `feature_flag.deleted`.

## Evaluate

`POST /v1/feature_flags/evaluate` with a `key` and a `context` (`organization_id`, `user_id`, `attributes`) returns the `variant`, its `value` and the `reason`. `POST /v1/feature_flags/evaluate_bulk` evaluates many flags at once. Evaluation needs the `feature_flags:evaluate` scope and reads no database, so it is fast and keeps working under load. From the CLI: `ohauthcat flags evaluate`.

An environment can hold up to 500 flags. Local evaluation inside the SDKs is planned.
