Authentication

The Management API authenticates with a bearer token in the Authorization header:

Authorization: Bearer <your-token>

There are two token types. Both are created in the Featureflip dashboard and are shown once at creation — store them securely. Creating either one requires a confirmed email address, so click the link in the verification email first. The security page explains how tokens and SDK keys are scoped.

Setting up a coding agent? Using an AI agent covers the handoff from your token to the agent’s first flag and SDK key.

Personal Access Tokens (ffp_)

A Personal Access Token acts as you: it carries your identity and your role in every organization you belong to. Use one for personal scripting, local tooling, or exploration.

Create one under Settings → API Tokens → Personal Access Tokens. A personal token is prefixed ffp_.

Service Tokens (ffs_)

A Service Token is a machine identity scoped to a single organization. It carries an explicit role and, optionally, an allowlist of projects it may access. Use one for CI, automation, or shared infrastructure — it is not tied to any person and keeps working after team changes.

Create one under Organization Settings → Service Tokens. A service token is prefixed ffs_.

Roles and permissions

Both token types act with a role. Roles are hierarchical — Owner is most privileged, Viewer least:

Role	Can do
Owner	Everything, including org settings
Admin	Manage projects, flags, members
Member	Create and edit flags, targeting, segments
Viewer	Read-only

A write performed by a token below the required role returns 403 forbidden. A service token whose project allowlist excludes the target project returns 404 not_found for that project.

Token expiry and errors

Tokens may have an expiry. A missing, malformed, expired, or revoked token returns 401 unauthorized:

{
  "error": "unauthorized",
  "message": "Missing or invalid API token.",
  "docs_url": "https://featureflip.io/docs/management-api/errors/unauthorized"
}

Two organization policies can also refuse a personal access token that is otherwise valid. Both come back as 403:

• two_factor_required: the organization requires two-factor authentication and the token’s owner hasn’t turned it on.
• token_lifetime_exceeds_policy: the token lasts longer than the organization allows. See below.

See Errors for the full error contract.

Maximum token lifetime

On the Business plan and above, an Owner can cap how long members’ personal access tokens last: 30, 90 or 365 days. Set it under Organization Settings → Security policies → Maximum personal access token lifetime.

A personal access token works in every organization its owner belongs to, so the strictest limit among them applies when you create one. With a 90-day limit in one of your organizations, every new token you make needs an expiry within 90 days, and the token form says which organization set it. The form lets you pick up to the 90th day from today, and the token lasts to the end of that day in your time zone. To allow for that, the API accepts an expiry up to 91 days after the token is created, and a refusal names the latest time it would accept, in UTC. Tokens that never expire can’t be created at all while a limit applies.

Tokens made before the limit keep working. The Security policies page lists the ones over it, with their owners, so an Owner can ask people to replace them. Once that’s done, turn on Refuse existing tokens over the limit. From then on this organization answers those tokens with 403 token_lifetime_exceeds_policy. Nothing is revoked, though. The same token still works in any of the owner’s other organizations that accept it.

Service tokens belong to one organization and set their own expiry, so the limit doesn’t apply to them.