Skip to content
FlagSwiftDocs

Key management

Create, rotate, reveal and revoke the keys that the Evaluation API accepts.

Concepts#

What a key is#

  • A key belongs to one project, and optionally to one environment (environmentId). It never reaches beyond that.
  • The secret starts with a prefix that names the type: fs_client_, fs_srv_ or fs_admin_. Lists show only the prefix and last four characters, as maskedKey.
  • Only a hash is used to check a key. The secret is also stored encrypted so an admin can copy it later; copyable says whether that is possible for a key.
  • A key's status is active, expired (past expiresAt) or revoked. Only active keys work, are rotated or can be revealed.
  • Creating, rotating, revoking and revealing are all audited, and never record the secret.

How rotation works#

Rotating issues a new key with the same name, type, project, environment and scopes, and returns its secret once. The old key is not cut off: its expiry is set to now plus overlapHours (default 24, and never later than an expiry it already had), so running deployments keep working while you roll the new secret out. With overlapHours of 0 the old key stops at once. The new key inherits the old key's expiry date, if it had one.

Rotating needs both api_keys.create and api_keys.revoke. After the overlap, the old key shows as expired; revoke it earlier once everything has switched.

Who can do what#

Developers, release managers and auditors can list keys (admin keys are left out of their list). Creating, rotating, revoking and revealing are held by organization admins.

Key types and scopes#

Which key to hand out, and the handling rules, are on the API keys page. Here are the values these endpoints take.

Key types and the scopes they get by default
TypeDescription
clientevaluation:read. Safe to ship in a browser or app. It is the only scope a client key may hold.
serverevaluation:read, flags:read, environment:read, kill_switch:execute. May hold only these.
adminevaluation:read, flags:read, flags:write, rollouts:write, environment:read, code_references:write. May also be given kill_switch:execute and audit:read.

The full scope list is evaluation:read, flags:read, flags:write, rollouts:write, environment:read, kill_switch:execute, audit:read and code_references:write. A key can never do more than the person who made it: each scope needs its creator to hold the matching permission.

Endpoints#

Create a key#

POST/api/api-keys

Returns 201 with the key, including the full secret, in this response only. Not cached.

Authorization

api_keys.create

Body

  • namestringRequired

    Up to 80 characters, trimmed. Shown in the audit log when the key acts.
  • typeclient | server | adminRequired

    See the table above. The type fixes which scopes the key may hold.
  • projectIdstringRequired

    The project the key covers. It cannot be archived.
  • environmentIdstring

    The environment id (not its name). Limits the key to one environment. Leave it out, or send it empty, for a project-wide key.
  • scopesstring[]

    One or more of the scopes above, each allowed for the type and held by you. Leave it out for the type's default scopes, narrowed to what you hold.
  • expiresInDaysinteger

    1 to 3650 (about 10 years). Leave it out, or send null or empty, for a key that does not expire.

Errors

  • 400“Name is required” (or “Name must be 80 characters or less”), “Key type is required” or “Choose a key type”, “Project is required”, an unknown scope, an empty scope list (“Choose at least one scope”), a scope the type cannot hold (“A client key cannot have the scope flags:write”), an expiresInDays that is not a whole number from 1 to 3650, invalid JSON, or “This project is archived. Restore it to issue API keys.”.
  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks api_keys.create, the organization is deactivated, the request was blocked as cross-site, or you asked for a scope you do not hold yourself (“A key cannot have more access than you do”).
  • 404“Project not found” (also for a deleted project), or the environment does not exist in your organization.
Request
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/api-keys" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout server",
    "type": "server",
    "projectId": "PROJECT_ID",
    "environmentId": "ENVIRONMENT_ID",
    "expiresInDays": 90
  }'
201Created
{
  "status": "success",
  "message": "API key created",
  "data": {
    "key": {
      "id": "9e3b6a52-0c41-4d87-a2f6-71d5c8e04b19",
      "name": "Checkout server",
      "type": "server",
      "maskedKey": "fs_srv_••••k7Qd",
      "copyable": true,
      "projectId": "PROJECT_ID",
      "projectName": "Web app",
      "environmentId": "ENVIRONMENT_ID",
      "environmentName": "Production",
      "scopes": ["evaluation:read", "flags:read", "environment:read", "kill_switch:execute"],
      "status": "active",
      "createdByEmail": "admin@example.com",
      "createdAt": "2026-10-03T09:00:00.000Z",
      "lastUsedAt": null,
      "expiresAt": "2027-01-01T09:00:00.000Z",
      "revokedAt": null
    },
    "secret": "fs_srv_Kq3xV9mT2bYp7LwR4sHn8ZcD6fGj1AeU"
  }
}

List keys#

GET/api/api-keys

Shows names, types, scopes, last use and status, never the secret. Admin keys are listed only to admins; for everyone else they are left out of the response, not just hidden on screen. The reply is a plain array, newest first, with no paging, and includes expired and revoked keys. lastUsedAt is updated at most once a minute per key.

Authorization

api_keys.read

Errors

  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks api_keys.read.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/api-keys"
200OK
{
  "status": "success",
  "message": "OK",
  "data": [
    {
      "id": "9e3b6a52-0c41-4d87-a2f6-71d5c8e04b19",
      "name": "Checkout server",
      "type": "server",
      "maskedKey": "fs_srv_••••k7Qd",
      "copyable": true,
      "projectId": "PROJECT_ID",
      "projectName": "Web app",
      "environmentId": "ENVIRONMENT_ID",
      "environmentName": "Production",
      "scopes": ["evaluation:read", "flags:read", "environment:read", "kill_switch:execute"],
      "status": "active",
      "createdByEmail": "admin@example.com",
      "createdAt": "2026-10-03T09:00:00.000Z",
      "lastUsedAt": null,
      "expiresAt": "2027-01-01T09:00:00.000Z",
      "revokedAt": null
    }
  ]
}

Rotate a key#

POST/api/api-keys/{id}/rotate

Issues a replacement and keeps the old key working for overlapHours (default 24, 0 to 720) so deployments can switch over without an outage. The new secret is returned once. Send a JSON body; {} uses the default. The reply is the new key and its secret; the old key keeps its own id.

Authorization

api_keys.create

Path parameters

  • idstringRequired

    The id of the key to replace. It must be active.

Body

  • overlapHoursinteger

    How long the old key keeps working, 0 to 720 (30 days). Default 24. 0 stops the old key at once. Never extends an expiry the old key already had.

Errors

  • 400Invalid JSON body (an empty body is not accepted: send {}), the project is archived, or an overlapHours that is not a whole number from 0 to 720.
  • 401No session, or it has expired (“Authentication required”).
  • 403You lack api_keys.create or api_keys.revoke, or you no longer hold a scope the key has.
  • 404“API key not found”, or its project or environment no longer exists.
  • 409“Only an active key can be rotated”: it is expired or revoked.
Request
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/api-keys/KEY_ID/rotate" \
  -H "Content-Type: application/json" \
  -d '{ "overlapHours": 24 }'
201Created
{
  "status": "success",
  "message": "API key rotated",
  "data": {
    "key": {
      "id": "4c8d2f71-5a93-4e60-b3d8-e2a07f1c9b46",
      "name": "Checkout server",
      "type": "server",
      "maskedKey": "fs_srv_••••w2Mx",
      "copyable": true,
      "projectId": "PROJECT_ID",
      "projectName": "Web app",
      "environmentId": "ENVIRONMENT_ID",
      "environmentName": "Production",
      "scopes": ["evaluation:read", "flags:read", "environment:read", "kill_switch:execute"],
      "status": "active",
      "createdByEmail": "admin@example.com",
      "createdAt": "2026-10-03T09:00:00.000Z",
      "lastUsedAt": null,
      "expiresAt": "2027-01-01T09:00:00.000Z",
      "revokedAt": null
    },
    "secret": "fs_srv_Wd8nT4qZ1xPv6RkL3yHb9McJ2sGf7AeU"
  }
}

Reveal a secret#

GET/api/api-keys/{id}/secret

Returns the full key to an admin. Every call is audited as api_key.revealed and the response is never cached. If the audit entry cannot be written, the secret is not handed over.

Authorization

api_keys.reveal

Path parameters

  • idstringRequired

    The key id. The key must be active and copyable.

Errors

  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks api_keys.reveal.
  • 404“API key not found”, or “This key was not stored, so it can't be copied” (copyable is false).
  • 409“Only an active key can be copied”.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/api-keys/KEY_ID/secret"
200OK
{ "status": "success", "message": "OK", "data": { "secret": "fs_srv_Kq3xV9mT2bYp7LwR4sHn8ZcD6fGj1AeU" } }

Revoke a key#

DELETE/api/api-keys/{id}

Revokes rather than deletes, so the key's audit trail keeps its context. Requests with it get AUTH_INVALID_API_KEY straight after.

Authorization

api_keys.revoke

Path parameters

  • idstringRequired

    The key id. Expired keys can be revoked too.

Errors

  • 401No session, or it has expired (“Authentication required”).
  • 403Your role lacks api_keys.revoke.
  • 404“API key not found”.
  • 409“This key is already revoked”.
Request
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/api-keys/KEY_ID"
200OK
{ "status": "success", "message": "API key revoked", "data": null }

Using the key

Send it as Authorization: Bearer … to the Evaluation API. Dashboard API calls never accept a key.
  • Deactivating the organization stops key requests too, until the owner reactivates it.

Common patterns#

Rotate a production server key with no downtime#

bash
# 1. Rotate. The old key keeps working for 48 hours. Save data.secret now: it is shown once.
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/api-keys/OLD_KEY_ID/rotate" \
  -H "Content-Type: application/json" -d '{"overlapHours":48}' | jq -r '.data.secret'

# 2. Deploy the new secret to your services, and watch lastUsedAt on the old key stop moving
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/api-keys" \
  | jq '.data[] | select(.name=="Checkout server") | {id, status, lastUsedAt, expiresAt}'

# 3. Optional: revoke the old key before the overlap ends
curl -s -b "auth_session=$SESSION" -X DELETE "$FLAGSWIFT_URL/api/api-keys/OLD_KEY_ID"

A narrow key for one environment#

bash
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/api-keys" \
  -H "Content-Type: application/json" \
  -d '{"name":"Staging reader","type":"server","projectId":"PROJECT_ID","environmentId":"STAGING_ENV_ID","scopes":["evaluation:read","flags:read"],"expiresInDays":30}'

Copy a key again#

If a key was created with copyable: true, an admin can fetch its secret again instead of rotating, and the access is audited.

bash
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/api-keys/KEY_ID/secret" | jq -r '.data.secret'