Feature flags

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:

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:

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.

{
  "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 for credentials.

Related

• Actions
• Vault
• Backend requests