Skip to content
FlagSwiftDocs

API keys

A key identifies an app or a service, limits what it can do, and acts with no more access than the person who created it.

Key types#

The three key types
TypePrefixDescription
Clientfs_client_…For browsers and mobile apps. Evaluation only: returns on/off results for one person. Safe to ship in an app.
Serverfs_srv_…For your backend. Reads full flag configuration and can use the emergency stop. Keep it secret.
Adminfs_admin_…For automation that manages flags, for example instant rollback from a pipeline. Never put it in an app.

Scope#

Every key belongs to one project and optionally one environment. A production-only key cannot read development, and the reverse. Limit keys to a single environment whenever the app only runs in one.

Scopes narrow what a key can call. A client key holds evaluation:read. Server keys add flags:read, environment:read and kill_switch:execute. Admin keys can also hold flags:write, rollouts:write, audit:read and code_references:write, which lets the code scanner report where flags are used. A key can never hold a scope its creator could not use themselves.

Create, rotate and revoke#

  • Create keys from the API Keys page. Only administrators can create, rotate and revoke keys.
  • Choose an expiry (30 days, 90 days, 1 year or never). A key that expires limits the damage if one leaks.
  • Rotating makes a new key with the same name, scope and target, and keeps the old one working for an overlap you choose (none, 1 hour, 24 hours or 7 days) so you can deploy the new one first.
  • Revoking stops a key immediately. Revoked and expired keys stay listed for the audit trail.

Storing and copying keys#

Keys are authenticated by their SHA-256 hash, and the full key is shown once when you create it. If your operator sets API_KEY_ENCRYPTION_KEY, new keys are also stored encrypted, and administrators can copy the full key again from the API Keys list. Each copy is recorded in the audit log. Keys created before that setting cannot be copied; rotate them to get one that can.

Treat keys like passwords

Keep server and admin keys in a secrets manager or private environment variables, never in source control or a client bundle. If one leaks, rotate it and choose Revoke the old key immediately.

Audit and use#

Key activity is audited as the key: creation, rotation, revocation, copying, and any change an admin key makes. The list shows when each key was last used, updated at most once a minute.