Authentication

All API endpoints (except /health, /docs, and /openapi.json) require a Bearer token for authentication.

Token format

Tokens follow the format ff_{prefix}_{random}:

• ff_ — fixed prefix identifying EdgeFlags tokens
• {prefix} — first 4 characters of the project ID (e.g., defa for default)
• {random} — 20 characters of cryptographically random data

Example: ff_defa_k1a2b3c4d5e6f7g8h9i0

Tokens are stored as SHA-256 hashes in the TOKENS KV namespace. The plaintext token is only returned once at creation time.

Permissions

Each token has an array of permissions that control access:

Permission	Description
read:flags	Evaluate flags, list flags
read:configs	Read config values, list configs
write:flags	Create, update, delete flags and segments
write:configs	Create, update, delete configs
*	Admin access (all permissions, plus token/webhook/audit management)

The * permission grants access to all endpoints including admin-only resources like tokens, webhooks, and audit logs.

Using tokens

Pass the token in the Authorization header:

curl -H "Authorization: Bearer ff_defa_k1a2b3c4d5e6f7g8h9i0" \
  "https://edgeflags.net/api/v1/flags/my_flag"

Creating tokens via API

Use an admin token (* permission) to create new tokens:

curl -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD read-only",
    "project_id": "default",
    "permissions": ["read:flags", "read:configs"]
  }' \
  "https://edgeflags.net/api/v1/tokens"

Response:

{
  "success": true,
  "token": "ff_defa_k1a2b3c4d5e6f7g8h9i0",
  "meta": {
    "name": "CI/CD read-only",
    "token_prefix": "ff_defa_k1a2",
    "project_id": "default",
    "permissions": ["read:flags", "read:configs"],
    "created_at": "2026-01-15T10:00:00.000Z"
  }
}

Save the token value immediately — it cannot be retrieved again.

Token expiration

Tokens can have an optional expires_at field (ISO 8601 timestamp). Expired tokens are rejected with a 401 response.

curl -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temporary staging access",
    "project_id": "default",
    "permissions": ["read:flags"],
    "expires_at": "2026-03-01T00:00:00Z"
  }' \
  "https://edgeflags.net/api/v1/tokens"

Listing tokens

List all tokens for your project (admin only). The plaintext token is never returned — only the prefix for identification.

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://edgeflags.net/api/v1/tokens"

Revoking tokens

Delete a token by its hash (admin only):

curl -X DELETE \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://edgeflags.net/api/v1/tokens/{hash}"