Authentication tokens for SDK and API access
Last updated November 14, 2026
API Tokens
Flaggr uses scoped API tokens for authenticating SDK and direct API requests.
Token Types
Project API Tokens
Long-lived tokens (fgr_…) for one project. Their scopes decide what they can reach. There are two kinds:
- API tokens, for one project's CI jobs, scripts and MCP server.
- SDK keys, for apps that evaluate flags. An SDK key is read-only and can't manage anything.
Create one in the console under Settings → API tokens, or with the API (Creating Tokens).
Authorization: Bearer fgr_xxxxxxxxxx
Personal Access Tokens
Account-level tokens (fgp_…) for Terraform, the Flaggr CLI, the local MCP server and scripts that span projects and organizations. A personal access token acts as you in every project you can access, limited to a read, write or admin tier, and can't evaluate flags. Create one under Profile → Personal access tokens — see Personal Access Tokens.
Authorization: Bearer fgp_xxxxxxxxxx
Legacy JWT tokens are short-lived access and refresh pairs. The console doesn't create them any more; see Legacy JWT tokens.
Which token should I use?
| Use case | Token |
|---|---|
| Apps that evaluate flags (SDKs, OFREP) | SDK key (fgr_…, read-only) |
| One project's CI job or script | Project API token (fgr_…) |
| Terraform, the Flaggr CLI, the local MCP server, scripts across projects | Personal access token (fgp_…) |
| Claude, ChatGPT, Cursor and other assistants | MCP connector — connect at /connect |
How API tokens are scoped
A project API token acts as the person who created it, but only inside its own project and never above that person's current role: its effective access is the token's tier capped by the creator's role. If the creator is demoted, the token's access shrinks with them; if they leave the project, the token stops working for management calls. Flag evaluation keeps working either way.
A token's access is a list of scopes. Each scope is <level>:<identifier>:<permission>:
| Level | Identifier | Covers | Example |
|---|---|---|---|
project | the project ID | everything in the project, including project-wide lists (services, flags) and settings | project:proj-1:read |
service | the service ID, not its slug or name | the flags of that service, in every environment | service:service-1712345:write |
environment | the environment slug | the flags of that environment, in every service | environment:production:read |
flag | the flag key | that flag, in every service and environment of the project | flag:checkout-v2:read |
The permission is read, write or admin, and each one includes the ones before it: admin includes write, and write includes read. A token made with the legacy permissions body gets one project scope:
| Scope permission | Legacy permissions body | What it can do |
|---|---|---|
read | read | Evaluate flags; read the project's flags, services, environments, metrics and audit data; send server telemetry events and spans for backend services (POST /api/ingest/server-events, read back through GET /api/analytics/server-events) |
write | read + write | Everything above, plus create, update and toggle flags and services, rollouts, alert rules and other project resources |
admin | + delete | Everything above, plus delete flags, services and monitors, change project settings and environments, and list, rename and revoke the project's tokens |
A project API token can never: reach another project; change organization resources (it may only read its own organization's basic info and that organization's project list, filtered to its project); create or delete projects or organizations; manage members, teams or invitations; issue credentials: create or rotate API tokens, create flag triggers, share links or invitation links; touch billing or SSO, or change the project's slug; call session-only endpoints (CLI device approval, webhooks, platform metrics, marking notifications read, the demo SDK key, invitation acceptance). Use the dashboard or a personal access token for these. Terraform, organization automation, deletes from the CLI and anything across projects also need a personal access token.
Rules add up. A request is allowed if any one of the token's scopes covers it. Scopes never subtract from each other.
A narrow rule covers only what it names. A service, environment or flag scope counts only on requests that name that service, environment or flag. Project-wide requests, such as a list of every service or flag in the project, need a project scope. A token with only narrow scopes can't make them. The access summary in the console warns about this as you build the rules.
SDK endpoints name a service, environment or flag too: evaluation (REST, OFREP, Connect, gRPC-Web), /api/sdk-config, the SSE streams (/api/flags/stream?serviceId=…&environment=…) and event ingestion (/api/events/outcomes, /api/events/exposures/batch, /api/evaluations, per event). So a service:service-1712345:read or environment:production:read key works as an SDK key for that service or environment, and a flag:<key>:read key works for requests that name only its flags (every flag in a batch). Endpoints that name none of them (token lists such as GET /api/users/me/tokens, organization info) need a project scope. On gRPC-Web, GetConfiguration and StreamFlags name flags only through flagKeys. The SSE streams forward each flag change only where the key covers that flag and environment.
A scoped token is checked when it is created or rotated:
- At least 1 and at most 50 scopes. A scope repeated in the list is stored once.
- Each scope matches the form above, with an identifier of letters, digits,
_,-and., and the whole scope is at most 512 characters. - A
projectscope must name this project. - A
servicescope must name a service ID of this project. A slug or a name is refused, and the error suggests the ID when one matches. - An
environmentscope must name one of this project's environment slugs. - A
flagscope is checked for its form only.
SDK keys
An SDK key is an opaque token created with evaluationOnly: true. Every scope of an SDK key must be read. It evaluates flags for the scopes it holds, and every management endpoint refuses it with 403. Create one with "tokenType": "opaque" and scopes. evaluationOnly is accepted only on that body: any other body that carries it is refused with 400, and so is one that puts it inside permissions.
Stored scopes
The control plane and the Go data plane (api.flaggr.dev) read a token's stored scopes the same way. A stored list that doesn't parse refuses the whole token: an empty list; more than 256 entries; an entry that isn't a string or is over 512 bytes (UTF-8); a scope that doesn't split into exactly three :-separated parts, has an unknown level or permission, or has an empty identifier or one with leading or trailing whitespace; or a project scope that names another project. Its creator can fix it by rotating it with a valid list of scopes (see Token Rotation), or revoke it.
Revocation and stream URLs
Revoking or rotating an opaque token (fgr_…) takes effect at once on the flaggr.dev server that handled the revocation and on the data plane (api.flaggr.dev), which looks every key up and caches none. For up to 5 seconds, though, the edge cache in front of api.flaggr.dev can still answer a request identical to one it has just answered (same URL, body and Authorization header). Other flaggr.dev servers stop accepting it within about 10 seconds (on deployments with a shared Redis or KV cache, such as flaggr.dev; without a shared cache, within about 30 seconds). JWT access tokens stay valid until they expire (at most 5 minutes). Open streams close within about a minute of a revocation, on api.flaggr.dev too (see Real-Time Updates).
A credential that Flaggr recognises but refuses (for example an SDK key on a management endpoint) gets 403 with an explanatory error rather than 401.
Credentials authenticate from the Authorization header. Stream URLs (?token=, for browsers' EventSource) take a signed-in session's ID token. The SDK streams (/api/flags/stream, /api/connect/stream) also take a read-only SDK key there: an evaluation-only or read-only fgr_ key, or a JWT whose scopes are all read. SDK keys ship in browser bundles anyway, and the key still has to cover the project, service, environment and flags the stream names. Personal access tokens, connector tokens, and keys that can write, delete or administer get 401 in any URL. /api/flags/{key}/metrics/stream and /api/ai/safety-alerts/stream accept no long-lived credential in the URL.
Demo SDK keys (evaluation-only)
Demo-enabled projects get a server-managed key named Demo Client Token. It authenticates flag evaluation and SDK traffic only: REST and OFREP evaluation, Connect and gRPC-Web, the SSE streams, /api/sdk-config, exposure and outcome events, and the data plane. Every management endpoint answers 403.
The demo page fetches the key after sign-in from GET /api/projects/{id}/demo/token. It is never rendered into page HTML or returned in project responses, and disabling the demo revokes it. Demo tokens minted before evaluation-only keys existed are treated as evaluation-only, and the deploy-time repair revokes them.
Creating Tokens
Via Dashboard
- Open the project in the console, go to Settings, then the API tokens tab.
- Choose Create token, and enter a name.
- Choose the type. An API token is for one project's CI jobs, scripts and MCP server. An SDK key is read-only, for apps that evaluate flags.
- Choose the access: Read-only, Read & write or Admin for the whole project (an SDK key offers Whole project), or Custom to add rules for the whole project, a service, an environment or a flag. Rules add up.
- Choose the expiry: 30 days, 90 days (the default), 1 year, No expiry, or Custom date.
- Choose Create token (Create SDK key for an SDK key), and copy the secret from the next step. Flaggr shows it once. The step also has copy-ready examples:
.env, MCP server andcurlfor an API token;.envand the SDK for an SDK key.
The row menu in the token list offers Rename, Change access (for the token's creator only), Rotate secret and Revoke. Changing access and rotating both issue a new secret. A legacy JWT row offers only Rename and Revoke: rotate a JWT with the API. On a service's Connection tab, Create token opens this dialog pre-filled as an SDK key limited to that service's read scope.
Via API
Creating a token is credential issuance. It needs a signed-in dashboard session whose email is verified, or an MCP connector with the admin tier (a connector whose consent narrowed the project needs admin on that project). API tokens and personal access tokens can't create tokens (403). Creating and rotating also need the manage_settings permission on the project, which the owner and admin roles have: a member or viewer gets 403. A dashboard session also needs a verified email: until your identity provider has verified the account's email, creating or rotating a token returns 403 { "error": "Verify your email address first", "code": "EMAIL_NOT_VERIFIED" }. In the console, choose Send verification email, open the link, then I've verified — retry; GitHub sign-ins need this once. MCP connectors are exempt — approving one already required a verified email. Token management runs on https://flaggr.dev; api.flaggr.dev only serves evaluation.
In the examples below, $ADMIN_TOKEN stands for a credential that may create tokens: a signed-in session's ID token or an admin-tier connector token.
The body picks the kind of token:
| Body | Creates |
|---|---|
"tokenType": "opaque" and scopes | A scoped, long-lived token. Its scopes decide its access, and expiresAt is optional. "evaluationOnly": true makes it an SDK key. |
permissions (no scopes) | A whole-project token from the legacy body. |
scopes and no tokenType (or "tokenType": "jwt") | A legacy JWT pair. See Legacy JWT tokens. |
A scoped token:
curl -s -X POST https://flaggr.dev/api/projects/proj-1/tokens \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON' | jq
{
"name": "checkout-ci",
"tokenType": "opaque",
"scopes": ["service:service-1712345:write", "environment:staging:read"],
"expiresAt": "2026-12-31T23:59:59.000Z"
}
JSON
# Response includes the token value once
# {
# "token": { "id": "token-1767225600000-k3x9q", "name": "checkout-ci", "tokenType": "opaque", "kind": "api_token",
# "scopes": ["service:service-1712345:write", "environment:staging:read"], ... },
# "value": "fgr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# }Leave out expiresAt for a token that never expires. When you set it, it must be a future timestamp ending in Z. The secret (value) is returned once, and the audit log records the scopes and expiry but never the secret.
A request that fails validation gets one of these 400 answers:
{ "error": "Validation Error", ... }: the name is longer than 100 characters, a scope doesn't match<level>:<identifier>:<permission>, there are more than 50 scopes, orexpiresAtisn't a future timestamp.{ "error": "Invalid scopes", "issues": [...] }: each issue names the scope it refers to and why it was refused."Demo Client Token" is reserved for the demo SDK key: the name is reserved (see Renaming Tokens).Choose scopes or permissions, not both — scopes decide a scoped token's access: a body with both.An SDK key needs tokenType "opaque" and read scopes:evaluationOnlyon any other body, or onpermissions.Request body must be a JSON object.
An Invalid scopes answer looks like this:
{
"error": "Invalid scopes",
"issues": [
{
"scope": "service:checkout:write",
"message": "Unknown service \"checkout\" in this project — use the service's id, not its slug or name (did you mean service:service-1712345:write?)"
}
]
}Whole-project tokens (legacy body)
A body with permissions and no scopes creates a whole-project token. Its read, write and delete bits give the tiers in the table above, and expiresAt is optional.
curl -s -X POST https://flaggr.dev/api/projects/proj-1/tokens \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "production-reader",
"permissions": { "read": true, "write": false, "delete": false },
"expiresAt": "2026-12-31T23:59:59.000Z"
}' | jq
# Response includes the token value — save it immediately
# {
# "token": { "id": "token-1767225600000-k3x9q", "name": "production-reader", ... },
# "value": "fgr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# }Legacy JWT tokens
A body with scopes and no tokenType (or with "tokenType": "jwt") creates a legacy JWT token (a row with tokenType: "jwt") plus an access and refresh pair, instead of an fgr_ secret:
{
"name": "Service JWT",
"scopes": ["project:proj-1:read"]
}The response carries the token row, an accessToken valid for 5 minutes and a refreshToken valid for 30 days, with their expiry timestamps. JWT scopes use the same form as the scopes above, but they are checked for their form only, when the token is created. Renew the pair with POST /api/projects/{id}/tokens/refresh: send tokenId and refreshToken in a JSON body, with no Authorization header. A refresh token works once. A refresh with a token that was already used, or one that has expired, gets 401.
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 fgr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"flagKey":"checkout-v2","serviceId":"web-app"}' | jqToken Rotation
Rotating a token issues a new secret and revokes the old one at once: anything still using the old secret stops working. Rotate with POST /api/projects/{id}/tokens/{tokenId}/rotate, or Rotate secret in the console (a legacy JWT row has no such action, so rotate a JWT with the API). The new token keeps the name and the creator. It acts as that creator, so rotating needs manage_settings (the owner and admin roles) and a project role at least as high as theirs. Rotation is credential issuance, like creating a token: API tokens and personal access tokens get 403, and an unverified session gets the same 403 EMAIL_NOT_VERIFIED.
Without a body, rotation keeps the name, the creator, the access and the expiry. The optional body changes them, for an opaque token:
{
"scopes": ["service:service-1712345:read"],
"expiresAt": null
}scopesreplaces the access. The new list is checked the same way as a new token's.expiresAtis a future timestamp, ornullfor a token that never expires.
Only the token's creator can send scopes or expiresAt. Anyone else gets 403 NOT_TOKEN_CREATOR. Anyone else with the manage-settings permission, and at least the creator's role, can still rotate the token without a body, and it keeps the creator's access and expiry.
An expired token rotates only with a new expiresAt, and only its creator can send one. Anyone else who sends it gets 403 NOT_TOKEN_CREATOR. A rotation without expiresAt, the creator's included, gets 409 TOKEN_EXPIRED. In the console, Rotate secret asks for a new expiry, which only the creator can set.
Change access in the console is the same request with scopes (and expiresAt, when it changes). Saving issues a new secret, which the console shows once.
A legacy JWT rotates with its own scopes and returns a new access and refresh pair with fresh expiries. A body that sets scopes or expiresAt on a JWT gets 400 JWT_BODY_NOT_SUPPORTED. The codes and the response shape are in the REST API Reference.
For zero-downtime rotation instead:
- Create a new token with the same access
- Update your application configuration
- Delete the old token
Renaming Tokens
Rename a token with PATCH /api/projects/{id}/tokens/{tokenId} and a body of { "name": "…" } (1 to 100 characters), or with Rename in the console. The secret, access and expiry stay the same, and no new secret is issued.
The name Demo Client Token is reserved for the demo SDK key. Creating a token with that name, or renaming one to it, returns 400. A token that already has the name can't be renamed (409 RESERVED_NAME), because the name is what marks it as the demo key.
Revoking Tokens
curl -s -X DELETE https://flaggr.dev/api/projects/proj-1/tokens/token-1767225600000-k3x9q \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "X-CSRF-Token: $CSRF_TOKEN"Security Best Practices
- Narrow the scopes. Give each token only the scopes it needs: a service, environment or flag scope where a project-wide one isn't needed. A project-wide list needs a
projectscope. - Use SDK keys in apps. An SDK key is read-only, only evaluates flags and can't manage anything, so it is the right key for code that ships to users.
- Set an expiry on every token. The console offers 30 days, 90 days, 1 year or a custom date. The API accepts any future
expiresAt. - 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