Create, rotate and revoke API keys
Give each app a key that can do only what it needs, replace it without downtime and cut it off when it leaks.
- Time
- About 12 min
- Who can do it
- Admins (api_keys.create, api_keys.revoke)
- Where
- API Keys, in the console
- You finish with
- A scoped key in your secrets store, with a plan to rotate it
What and why#
An API key is how an app or a script proves it may talk to the Evaluation API. A key belongs to one project, optionally to one environment, has a type that decides what it may do, and can expire. Because a leaked key is a leaked credential, FlagSwift stores only a hash of it and shows the full value once.
One key per job#
Create a key per app and environment rather than sharing one. A key named “Checkout service (prod)” tells you what to rotate when that service changes hands, shows its own last-used time, and appears by name in the audit log when it acts.
Keys act for a person, never beyond them#
A key can never hold a scope its creator could not use. A key made by someone with less access is narrower, and a key used for rollback is recorded in the audit log under the key's name.
Before you start#
- Creating a key takes
api_keys.create, revoking takesapi_keys.revoke, rotating takes both, and copying a full key takesapi_keys.reveal. Of the built-in roles only admins hold them. Release managers, developers and auditors can see keys but not manage them. - Decide where the key will run. A browser or mobile app gets a client key. A backend gets a server key. Automation that changes flags gets an admin key.
- Have a secrets manager or private environment variables ready for server and admin keys.
- The project must not be archived. An archived project refuses new keys until it is restored.
Key types#
| Type | Prefix | Description |
|---|---|---|
| Client | fs_client_… | Evaluation only, for one person. Safe to ship in an app. Holds evaluation:read. |
| Server | fs_srv_… | Reads full configuration and can use the kill switch. Adds flags:read, environment:read and kill_switch:execute. Keep it secret. |
| Admin | fs_admin_… | Can also hold flags:write, rollouts:write, audit:read and code_references:write. Never put it in an app. |
A key can never hold a scope its creator could not use, so a key made by someone with less access is narrower. A new admin key gets evaluation:read, flags:read, flags:write, rollouts:write, environment:read and code_references:write by default.
Walk through it#
Create a key
Open API Keys and press New API Key. The dialog is titled Create API Key.
Create API Key Field Rule Description Name Required, up to 80 characters Shown in the list and in the audit log when the key acts. For example “Checkout service (prod)”. Type Default Server Client, Server or Admin. The hint under the field explains the one you pick. Project Required The project the key covers. A key never reaches another project. Environment Default All environments Limit a production key to production only. A key limited to one environment always evaluates that environment. Expires Default Never Never, 30 days, 90 days or 1 year. Keys that expire limit the damage if one leaks. The Create API Key dialog. The hint under Type changes with your choice. Save the secret
The full key is shown once, with a Copy button. Put it in your secrets store, then press I've saved it. After that only the prefix and the last four characters are shown.
The only time the whole key is shown. Closing the dialog discards it. Copying it again
People who holdapi_keys.revealcan copy a key from the list only if the operator setAPI_KEY_ENCRYPTION_KEYbefore the key was created. Each copy is audited asapi_key.revealed. Otherwise the copy button is disabled and you must rotate to get a new secret.You should see. The key appears in the list as Active with its type, project and environment, and shows Never used until it is called.Read the list
Five cards at the top count Active, Total keys (with the client, server and admin split), Expiring soon (active keys ending within 30 days), Expired and Revoked keys. The Expired and Revoked cards open read-only tables of those keys. A key about to expire carries an Expires in N days badge. Each row shows when the key was last used, when it expires and who created it. The page groups keys under Client, Server and Admin, then by project. Open a project to see only its keys, ten to a page, with search and filters for status, type and environment; New API Key there starts with that project selected.
The key list: status cards and one row per key with its rotate and revoke actions. Rotate on a schedule or after a change of hands
Use the rotate action on an active key. Choose how long the old key keeps working: immediately, 1 hour, 24 hours (recommended) or 7 days. The new key has the same name, scope and target and keeps the same expiry. Deploy it, confirm the old one is no longer used, and let the overlap end. An overlap never lengthens an expiry the old key already had.
The rotate dialog. 24 hours is preselected, and choosing the first option turns the confirm button red. You should see. A second dialog shows the new secret once. The old key stays Active until the overlap ends, then shows as Expired.Revoke a leaked key
Press the revoke action and confirm. Anything using the key stops working immediately and this cannot be undone. Revoked and expired keys stay in the list, under their status filters, for the audit trail.
The confirmation before a key is revoked, and the same dialog while the request runs: Cancel and the close button are disabled and the button shows a spinner until it finishes.
Do it with the API
It needs api_keys.create. expiresInDays is a whole number from 1 to 3650; leave it out for a key that never expires. scopes is optional and defaults to the type's scopes, narrowed to what you hold. Rotate with POST /api/api-keys/{id}/rotate and body { "overlapHours": 24 } (0 to 720), revoke with DELETE /api/api-keys/{id}. See the Key management API.
# Key management is part of the Dashboard API: sign in first (POST /api/auth/login,
# keep the cookie). An API key cannot create other keys.
curl -s -b jar.txt -X POST https://flags.example.com/api/api-keys \
-H "Content-Type: application/json" \
-d '{
"name": "Checkout service (prod)",
"type": "server",
"projectId": "PROJECT_ID",
"environmentId": "ENVIRONMENT_ID",
"expiresInDays": 90
}'{
"status": "success",
"message": "API key created",
"data": {
"key": {
"id": "key_123",
"name": "Checkout service (prod)",
"type": "server",
"maskedKey": "fs_srv_••••k3Qz",
"copyable": false,
"projectId": "PROJECT_ID",
"projectName": "Web",
"environmentId": "ENVIRONMENT_ID",
"environmentName": "production",
"scopes": ["evaluation:read", "flags:read", "environment:read", "kill_switch:execute"],
"status": "active",
"createdByEmail": "you@example.com",
"createdAt": "2026-10-03T09:30:00.000Z",
"lastUsedAt": null,
"expiresAt": "2027-01-01T09:30:00.000Z",
"revokedAt": null
},
"secret": "fs_srv_...shown-once..."
}
}Check a key still works
This is the Evaluation API, which does take a key as a bearer token. A project-wide key must say which environment with ?env=; a key limited to one environment does not need it.
curl -s -X POST "https://flags.example.com/api/v1/evaluation/client?env=production" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"identifiers":["user-123"]}'Good to know#
Admin keys stay out of sight
Set an expiry you will actually honour
Can I change a key's type or scopes after creating it?
Does rotating break my running app?
What does a revoked key return?
AUTH_INVALID_API_KEY, the same as for an unknown or expired key.Is a client key really safe in a browser?
If something goes wrong#
Requests fail with AUTH_INVALID_API_KEY
Why: The key is unknown, revoked or expired, or it was copied incompletely.
Fix: Check its status on the API Keys page. If it is revoked or expired, create or rotate a key and deploy the new value.
Only an active key can be rotated
Why: The key is already expired or revoked.
Fix: Create a new key with the same settings instead.
This key was not stored, so it can't be copied
Why: The operator had not set API_KEY_ENCRYPTION_KEY when the key was created, so only a hash exists.
Fix: Rotate the key to get a new secret, and save it when it is shown.
This project is archived. Restore it to issue API keys.
Why: Keys cannot be created or rotated for an archived project.
Fix: Restore the project, then create or rotate the key.
A key cannot have more access than you do
Why: You asked for a scope your own role does not allow, for example an admin scope without the matching permission.
Fix: Ask for fewer scopes, or have an admin create the key.
What to check#
- The list shows when the key was last used. A key marked Never used is a candidate for revoking.
- After a rotation, the old key is not used any more before its overlap ends.
- After a revoke, requests with the key fail with
AUTH_INVALID_API_KEY. - Creation, rotation, revocation and copying appear in the audit log as
api_key.created,api_key.rotated,api_key.revokedandapi_key.revealed.