Skip to main content

Authentication methods, API token types and scopes, project roles, and permissions model

Last updated November 14, 2026

Authentication & Tokens

Flaggr supports multiple authentication methods for different use cases -- Firebase session auth for the dashboard, and API tokens (opaque or JWT) for programmatic access.

Authentication Methods

Dashboard (Firebase Auth)

The Flaggr dashboard uses Firebase Authentication. Users sign in via Google, GitHub, or email/password credentials. Sessions are managed via secure HTTP-only cookies.

Signing in with an email that already belongs to a Flaggr account links to that account only when your identity provider has verified the address. If the account was bound to another sign-in identity that also verified the address — for example your organization's SSO and your Google account — switching between them changes nothing else. If the previous identity didn't verify the address (or can't be checked), the account's personal access tokens and connector (MCP) grants are revoked, every pending invitation it created is withdrawn, and the event is audited (user.identity_relinked, which lists the withdrawn invitations and the members of the organizations and projects it manages, for review).

Until your email is verified you can use the dashboard, but you can't create or rotate personal access tokens or project API tokens, approve connector (OAuth) or CLI sign-ins, or accept invitations (403 "Verify your email address first"). That includes the read-only token the console's onboarding Connect step creates.

GitHub sign-ins start unverified. Firebase doesn't treat GitHub addresses as verified, so a GitHub account, like a new email/password account, verifies its address once. The console shows a banner, and wherever an action needs the verified address, a notice with Send verification email. Open the link in that email, then choose I've verified — retry (or I've verified on the banner), which refreshes your session so the API sees the verified address. If the console can't check (you're offline, or your session expired), it says so and the banner stays up: try again, or sign in again. Google and organization SSO sign-ins are verified already. The address you verify must be your Flaggr account's email.

Organization SSO sign-ins are accepted only while the SSO connection is active, claims your email domain, and its organization has verified that it owns the domain (see Organization SSO). SSO sign-ins link an existing account by email only on such a verified domain, and platform admin addresses never sign in through SSO. Only the connection's own SAML or OIDC provider signs anyone in through its tenant: other sign-in methods a tenant can enable (email/password, email link, phone, anonymous) are refused. Enforced SSO applies only to active connections on domains their organization verified; draft or disabled connections, and unverified domains, never block sign-in.

Organization SSO

SAML or OIDC single sign-on (enterprise plan) is configured per organization under Single Sign-On in the organization's settings, from a signed-in dashboard session only.

  1. Create the connection (Create draft). It starts as a draft. Public email providers (gmail.com, outlook.com, hotmail.com, yahoo.com, icloud.com, proton.me, gmx.com, …) can't be claimed.
  2. Prove you own each domain. Under Domain ownership, Get TXT record shows a DNS record to publish: name _flaggr-sso.<domain>, value flaggr-sso-verification=<token>. Then choose Verify. A domain can be verified by only one organization at a time.
  3. Activate. A connection can be active only while every domain it claims is verified by its organization and no other connection of the organization claims it.

API (listing needs read access to the organization; the changes need an organization admin's dashboard session):

  • GET /api/organizations/{orgId}/sso/domains: each domain's status (verified, pending, unverified) and the TXT record to publish.
  • POST /api/organizations/{orgId}/sso/domains { "domain" }: issue the challenge (201). 400 public email provider (PUBLIC_EMAIL_DOMAIN), 409 verified by another organization (DOMAIN_VERIFIED_BY_ANOTHER_ORG), 402 plan.
  • POST /api/organizations/{orgId}/sso/domains/{domain}/verify: 200 verified; 422 record missing or wrong (code: "DOMAIN_NOT_VERIFIED"); 404 no challenge yet.
  • DELETE /api/organizations/{orgId}/sso/domains/{domain}: release the domain. 409 (DOMAIN_IN_USE) while an active connection uses it.

Activating a connection with an unverified domain returns 409 with code: "DOMAIN_NOT_VERIFIED" and a problems list. Bring-your-own GCIP projects belong to one organization (409 BYO_PROJECT_IN_USE), and the service account must be able to list the project's tenants (Identity Toolkit Admin; otherwise 400 BYO_CREDENTIALS_INVALID).

Just-in-time membership is granted when someone signs in through SSO (not on every request) and needs a free plan seat. When it adds you to the organization, your pending invitations to that organization are withdrawn (audited as org.invitation_cancel). Removing an SSO member, or the member leaving, stops just-in-time provisioning from adding them back until an admin re-adds them or they accept an invitation; also deprovision them in your identity provider. If Flaggr can't record that, the removal fails (500, the member stays) and can be retried. Deleting an organization deletes its SSO connections and their identity-provider tenants. Operators can verify a domain out of band with scripts/verify-sso-domain.ts.

API Tokens (Bearer)

For programmatic access from SDKs, CI/CD pipelines, and service-to-service communication:

Authorization: Bearer fgr_your_token

Personal Access Tokens

For automation that spans projects and organizations — Terraform, the Flaggr CLI, the local MCP server, scripts — use a personal access token. It acts as you, limited to its tier (read, write or admin), and expires after 7–365 days:

Authorization: Bearer fgp_your_token

SDK and evaluation endpoints reject personal access tokens. See Personal Access Tokens.

Public Flags

Flags marked as isPublic: true can be evaluated without authentication on flaggr.dev with POST /api/flags/evaluate, which suits client-side flags where embedding a token isn't appropriate; an unauthenticated GET /api/sdk-config?serviceId=…&bootstrap=1 also includes their configuration. Batch evaluation, OFREP, Connect and the streams still need a credential, and the data plane at api.flaggr.dev, which @flaggr/sdk uses by default, always needs a key.

Token Types

Project API Tokens

Long-lived bearer tokens (fgr_…) for one project. Their scopes decide what they can reach, and they don't need a refresh. An SDK key is a project API token created with evaluationOnly: true.

POST /api/projects/{id}/tokens
 
{
  "name": "checkout-ci",
  "tokenType": "opaque",
  "scopes": ["service:service-1712345:write", "environment:staging:read"],
  "expiresAt": "2026-12-31T00:00:00Z"
}

Response (token value shown only on creation):

{
  "token": {
    "id": "token-1767225600000-k3x9q",
    "name": "checkout-ci",
    "tokenType": "opaque",
    "kind": "api_token",
    "scopes": ["service:service-1712345:write", "environment:staging:read"],
    "expiresAt": "2026-12-31T00:00:00Z",
    "createdAt": "2025-07-20T10:00:00Z"
  },
  "value": "fgr_abc123def456..."
}

Store the value securely -- it cannot be retrieved again.

Scopes have the form <level>:<identifier>:<permission>: project:<id>, service:<id> (the service's ID, not its slug), environment:<slug> or flag:<key>, with read, write or admin. A request is allowed if any scope covers it. A token made with the legacy permissions body (read, write, delete) covers the whole project. See How API tokens are scoped.

Legacy JWT Tokens

Legacy short-lived access and refresh pairs. A body with scopes and no tokenType still creates one, but project API tokens above are the choice for new integrations.

POST /api/projects/{id}/tokens
 
{
  "name": "Service JWT",
  "scopes": ["project:proj_a1b2c3d4:write"]
}

Response:

{
  "token": {
    "id": "token-1767225600000-k3x9q",
    "name": "Service JWT",
    "tokenType": "jwt",
    "scopes": ["project:proj_a1b2c3d4:write"],
    "createdAt": "2025-07-20T10:00:00Z"
  },
  "accessToken": "eyJhbGciOiJ...",
  "refreshToken": "eyJhbGciOiJ...",
  "accessTokenExpiresAt": "2025-07-20T10:05:00Z",
  "refreshTokenExpiresAt": "2025-08-19T10:00:00Z"
}

Scopes have the form <level>:<identifier>:<tier>: project:<id>, service:<id>, environment:<name> or flag:<key>, with read, write or admin.

JWT Claims Structure

When decoded, a Flaggr JWT access token contains the following claims:

{
  "sub": "token-1767225600000-k3x9q",
  "iss": "flaggr",
  "aud": "flaggr-api",
  "iat": 1721473200,
  "exp": 1721473500,
  "jti": "unique-token-id-abc",
  "pid": "proj_a1b2c3d4",
  "uid": "user_123",
  "scopes": ["project:proj_a1b2c3d4:write"],
  "kind": "access"
}
ClaimDescription
subToken ID (subject)
issAlways "flaggr"
audAlways "flaggr-api"
iatIssued-at timestamp (Unix seconds)
expExpiration timestamp (Unix seconds)
jtiUnique token identifier
pidThe project this token belongs to
uidThe user who created the token; the token acts as them
scopesArray of granted scopes
kind"access" or "refresh"

Legacy JWT Lifecycle

Create token → Receive access + refresh tokens
  │
  ├─ Access token (5 min TTL)
  │   ├─ Use for API requests
  │   ├─ Include in Authorization header
  │   └─ On 401 → use refresh token
  │
  └─ Refresh token (30d TTL)
      ├─ Exchange for new access + refresh pair
      ├─ Old refresh token is invalidated (rotation)
      └─ If expired → create new token from dashboard

Access tokens expire after 5 minutes. Refresh tokens expire after 30 days. When you refresh, both the access and refresh tokens are rotated -- the old refresh token is invalidated immediately to prevent replay attacks.

Refreshing JWT Tokens

The refresh request is unauthenticated: the refresh token proves the caller. Send the token's id and the refresh token in a JSON body, with no Authorization header.

POST /api/projects/{id}/tokens/refresh
Content-Type: application/json
 
{ "tokenId": "token-1767225600000-k3x9q", "refreshToken": "eyJhbGciOiJ..." }

Returns new access and refresh tokens:

{
  "accessToken": "eyJhbGciOiJ...(new)",
  "refreshToken": "eyJhbGciOiJ...(new)",
  "accessTokenExpiresAt": "2025-07-22T10:00:00Z",
  "refreshTokenExpiresAt": "2025-08-21T10:00:00Z"
}
Refresh token rotation

Each refresh token is single-use. After a successful refresh, the previous refresh token is refused: a reused or expired refresh token gets 401, and you create a new token to start again.

SDKs should implement proactive refresh to avoid interruptions:

// Refresh when the access token has < 60 seconds remaining
const REFRESH_BUFFER_MS = 60 * 1000
 
async function ensureValidToken(tokenState: TokenState): Promise<string> {
  const now = Date.now()
  const expiresAt = tokenState.accessTokenExpiresAt.getTime()
 
  if (expiresAt - now > REFRESH_BUFFER_MS) {
    return tokenState.accessToken // Still valid
  }
 
  // Proactively refresh. tokenId is the token's id from the create response; the
  // refresh token goes in the body, not in Authorization.
  const response = await fetch(`/api/projects/${projectId}/tokens/refresh`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ tokenId: tokenState.tokenId, refreshToken: tokenState.refreshToken }),
  })
 
  const { accessToken, refreshToken, accessTokenExpiresAt } = await response.json()
  tokenState.accessToken = accessToken
  tokenState.refreshToken = refreshToken
  tokenState.accessTokenExpiresAt = new Date(accessTokenExpiresAt)
 
  return accessToken
}

Refresh tokens are single-use, so serialize refreshes: when several callers find the access token expiring, they should share one in-flight refresh promise. A caller that loses the race presents a refresh token that is already used and gets 401.

Permissions Model

Project Roles

RoleFlagsServicesMembersSettingsDelete Project
OwnerRead/Write/DeleteRead/Write/DeleteManageManageYes
AdminRead/Write/DeleteRead/Write/DeleteManageManageNo
MemberRead/WriteRead/WriteViewNoNo
ViewerReadReadViewNoNo

Token Scopes

A project API token is capped by its scopes: the project, service, environment and flag rules it holds, which add up. A token made with the legacy permissions body is capped by its tier: read, write, or admin (the Delete permission). See How API tokens are scoped.

Personal Access Token Tiers

Your project and organization roles always apply; the tier caps them further.

TierAdds
readGET requests, plus the POSTs that only read (explain, simulate, advice, code references, cohort evaluation)
writeCreate, change and delete flags, services, rollouts, alert channels and rules, metric sources
adminMembers, teams, environments, project and organization settings, listing and revoking project API tokens, creating organizations and projects
Owner actions (admin opt-in)Deleting projects and organizations, ownership changes — the owner role is still required

CSRF Protection

All state-changing requests from the dashboard require a CSRF token:

# 1. Get CSRF token
GET /api/csrf-token
# → { "token": "abc123", "headerName": "x-csrf-token" }
 
# 2. Include in mutation requests
POST /api/flags
X-CSRF-Token: abc123
Content-Type: application/json
 
{ ... }

Bearer authentication (API tokens, personal access tokens, dashboard ID tokens) does not require CSRF tokens -- CSRF protection only applies to cookie-based sessions.

Token Management

List All Tokens for a Project

GET /api/projects/{id}/tokens

List Your Tokens Across All Projects

GET /api/users/me/tokens

Returns token metadata only (never hashes). API tokens, personal access tokens and connectors need admin access; API tokens and connectors see only the projects they are bound to.

Revoke a Token

DELETE /api/projects/{id}/tokens/{tokenId}

A revoked opaque token is refused at once by the flaggr.dev server that handled the revocation and by the data plane (api.flaggr.dev), which caches no credentials. 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). Every other flaggr.dev server stops 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). Deleting a project revokes all of its tokens. JWT access tokens are self-contained and stay valid until they expire (at most 5 minutes); revoking the token prevents refreshing it. Open streams close within about a minute of a revocation, on api.flaggr.dev too (see Real-Time Updates).

Personal Access Tokens (signed-in session only)

GET    /api/users/me/personal-tokens
POST   /api/users/me/personal-tokens
DELETE /api/users/me/personal-tokens/{id}
POST   /api/users/me/personal-tokens/{id}/rotate

API tokens, personal access tokens and connectors get 403 on these. See Personal Access Tokens.

Authentication Flow Diagrams

SDK Authentication (Opaque Token)

SDK                                Flaggr API
 │                                      │
 ├─ POST /api/flags/evaluate ──────────►│
 │  Authorization: Bearer fgr_xxx       │
 │                                      ├─ Hash token
 │                                      ├─ Lookup in token store
 │                                      ├─ Check permissions
 │                                      ├─ Check expiration
 │                                      ├─ Evaluate flag
 │◄──────────── 200 OK ────────────────┤
 │  { value: true, reason: "..." }      │

SDK Authentication (JWT Token)

SDK                                Flaggr API
 │                                      │
 ├─ POST /api/flags/evaluate ──────────►│
 │  Authorization: Bearer eyJhbG...     │
 │                                      ├─ Verify JWT signature
 │                                      ├─ Check exp claim
 │                                      ├─ Check pid is the project
 │                                      ├─ Extract scopes
 │                                      ├─ Evaluate flag
 │◄──────────── 200 OK ────────────────┤
 │                                      │
 │  ... 5 min later, access token expired│
 │                                      │
 ├─ POST /tokens/refresh ──────────────►│
 │  JSON: tokenId, refreshToken, no auth│
 │                                      ├─ Verify refresh JWT
 │                                      ├─ Rotate tokens
 │◄──────── New access + refresh ──────┤

Best Practices

  • Use SDK keys in apps -- an SDK key only evaluates flags, and every scope it holds must be read
  • Set expiration dates on tokens, especially for CI/CD
  • Scope tokens narrowly -- give a service, environment or flag scope where a project-wide one isn't needed
  • Use scoped project API tokens for services and CI -- they are long-lived and need no refresh, so set an expiry and rotate them
  • Rotate tokens regularly -- rotating issues a new secret and revokes the old one at once, so switch your configuration first
  • Use public flags for client-side feature flags to avoid embedding tokens in frontend code
  • Never commit tokens to version control -- use environment variables
  • Implement proactive refresh for legacy JWT tokens to avoid request failures at expiration boundaries
  • Never ship a personal access token in an app -- it acts as you across every project; SDKs use project API tokens
  • Use personal access tokens for Terraform and cross-project scripts, with the lowest tier that works and an expiry