Personal Access Tokens

A personal access token (fgp_…) belongs to you and covers your whole account. It acts as you in every project and organization you can access, limited to the tier you pick when you create it. Use it for automation that spans projects: the Terraform provider, the Flaggr CLI, the MCP server over stdio and your own scripts.

Your roles always apply as well. A token never does more than you can do yourself — if you lose access to a project, every token you own loses it too.

Which token should I use?

Format

fgp_3f9a…   # fgp_ followed by 64 lowercase hex characters (32 random bytes)

• Flaggr stores only the SHA-256 hash of the secret, plus its last 4 characters so you can tell tokens apart (fgp_…a1b2). The secret is shown once, when the token is created or rotated.
• Secret scanners can match the pattern fgp_[0-9a-f]{64}.

Tiers

Owner actions

Deleting a project or an organization, and ownership changes (granting the owner role, demoting or removing an owner, transferring ownership), are owner actions. An admin token can do them only if you tick Allow owner actions when you create it — it's off by default and not available on other tiers. You still need the owner role yourself.

Terraform needs owner actions for terraform destroy, or to remove a flaggr_project or flaggr_organization resource. Without the opt-in those deletes fail with HTTP 403.

Limits

• Up to 20 active tokens per user (expired and revoked tokens don't count).
• Every token expires: choose 7, 30, 90 (default), 180 or 365 days. Rotate a token before it expires to keep the same name, tier and lifetime.

Creating a token

In the dashboard

1. Open Profile → Personal access tokens (/console/profile#personal-access-tokens).
2. Click New token, name it (e.g. Terraform (production)), pick a tier and an expiry.
3. For Terraform deletes, choose Admin and tick Allow owner actions.
4. Copy the token — it won't be shown again.

With flaggr login

Install the Flaggr CLI from github.com/flaggr-dev/flaggr-cli (see CLI).

flaggr login (and the MCP server's login tool) open /auth/cli. Choose All my projects to mint a write personal access token that expires in 90 days and is saved to ~/.flaggr/config.json. One project still mints a project API token. The page hands the token to the CLI (or the MCP server) in a form POST to its localhost callback — never in a URL, which your browser history would keep. A CLI or MCP server older than this release gets an "out of date" message and no token: update it, or create a token here and run flaggr login --token.

Management endpoints

Personal access tokens are managed only from a signed-in dashboard session. These endpoints refuse every token — connector, project API token, JWT or personal access token:

Creating or rotating a token also needs a verified email address: an unverified session gets 403 with "error": "Verify your email address first" and code: "EMAIL_NOT_VERIFIED". Listing and revoking work either way.

Using a token

Send it as a Bearer token to the control plane, https://flaggr.dev:

export FLAGGR_API_TOKEN="fgp_your_token_here"
 
# Who is this token, and what can it reach?
curl -s https://flaggr.dev/api/users/me -H "Authorization: Bearer $FLAGGR_API_TOKEN" | jq '.credential'

• Terraform reads FLAGGR_API_TOKEN (or the provider's api_token).
• CLI: flaggr login --token fgp_… saves it.
• MCP server over stdio: set FLAGGR_API_TOKEN in the server's env.

Not for evaluation

The SDK and evaluation endpoints (/api/flags/evaluate, /api/ofrep/*, Connect and gRPC-Web, /api/sdk-config, SSE streams, event ingestion) reject personal access tokens with 403. The data plane at api.flaggr.dev refuses them too. Until the data plane update, it treats a personal access token like any key it doesn't know: 401 {"error":"UNAUTHENTICATED"}, and unauthenticated for Connect and gRPC-Web calls (flaggr eval included). After the update:

• REST and SSE requests get 403 {"error":"FORBIDDEN","message":"personal access tokens can't evaluate flags or call SDK endpoints — use a project API token (SDK key)"}.
• Single-flag OFREP requests get 403 {"key":"<flag>","errorCode":"PROVIDER_NOT_READY","errorDetails":"Forbidden: personal access tokens can't evaluate flags or call SDK endpoints — use a project API token (SDK key)"}.
• Connect and gRPC-Web calls get PERMISSION_DENIED with the same message.

The MCP tools evaluate_flag, watch_flag_updates and measure_round_trip, and flaggr eval, need a project API token:

FLAGGR_API_TOKEN=fgr_your_project_token flaggr eval bool -k new-checkout -s <service-id>

What a personal access token can never do

So a leaked token can't outlive its own revocation or widen its access, personal access tokens never:

• create or rotate project API tokens, flag trigger URLs, share links (view or toggle) or invitations;
• approve OAuth consent or CLI/device logins, or manage MCP connections;
• accept invitations;
• change SSO configuration, open billing checkout or the billing portal, or set up demo data;
• create, rotate or revoke personal access tokens.

Use the dashboard for these.

Rotation and revocation

Revoking or rotating a token takes effect immediately; other servers stop accepting the old secret within about 10 seconds (within about 30 seconds on a deployment without a shared cache). Rotation issues a new secret with the same name, tier, owner-actions setting and lifetime (or a new expiresInDays) and revokes the old one at once — update the secret wherever it's stored. Expired tokens can't be rotated; create a new one.

flaggr logout and the MCP server's logout tool only forget the token on that machine; it keeps working until you revoke it here or it expires.

Errors