API Tokens

Flaggr uses scoped API tokens for authenticating SDK and direct API requests.

Token Types

Project API Tokens

Project-scoped tokens for SDK and API access. Created in the project settings dashboard.

Authorization: Bearer flg_proj_xxxxxxxxxx

User JWT Tokens

Short-lived tokens issued during user authentication. Used by the dashboard and admin APIs.

Token Scopes

Scope	Permissions
`read`	Evaluate flags, list flags
`write`	Create, update, delete flags
`admin`	Manage project settings, tokens, members

Creating Tokens

Via Dashboard

Navigate to Project Settings > API Tokens
Click Create Token
Select the required scopes
Copy the token immediately (it won't be shown again)

Via API

curl -s -X POST https://api.flaggr.dev/api/projects/proj-1/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-reader",
    "scopes": ["read"],
    "expiresIn": "90d"
  }' | jq
 
# Response includes the token value — save it immediately
# {
#   "token": { "id": "tok_...", "name": "production-reader", ... },
#   "value": "flg_proj_xxxxxxxxxxxxxxxxxxxx"
# }

Verifying a Token

After creating a token, verify it works by evaluating a flag.

curl -s https://api.flaggr.dev/api/flags/evaluate \
  -H "Authorization: Bearer flg_proj_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"flagKey":"checkout-v2","serviceId":"web-app"}' | jq

Token Rotation

Tokens can be rotated without downtime:

Create a new token with the same scopes
Update your application configuration
Delete the old token

Revoking Tokens

curl -s -X DELETE https://api.flaggr.dev/api/projects/proj-1/tokens/tok_old_token_id \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "X-CSRF-Token: $CSRF_TOKEN"

Security Best Practices

Use read-only tokens for client-side SDKs
Set expiration dates on all tokens
Rotate tokens regularly (every 90 days recommended)
Never commit tokens to version control
Use environment variables for token storage
Use separate tokens per service/environment

Next→