Use the Management API from an AI agent

This page is for coding agents (Claude Code, Codex, Cursor and the like) and for the people who set them up. An agent can do everything in the Management API with one bearer token. A person has to create that token in the dashboard, and after that the agent needs nothing else from them.

Step 1: a person creates the token

API tokens are created in the dashboard, and only once the account’s email address is confirmed. A token can’t create another token. So the first credential always comes from a person, in three steps:

1. Sign up at app.featureflip.io/signup and click the link in the verification email.
2. Create a token. For an agent working in one codebase, a Service Token (Organization Settings → Service Tokens) is the better fit: it belongs to the organization, carries a role you choose and can be limited to certain projects. A Personal Access Token (Settings → API Tokens) acts as you, with your role in every organization you belong to.
3. Give it to the agent as FEATUREFLIP_TOKEN. The value is shown once, at creation.

Authentication covers both token types and the roles.

Step 2: the agent checks the token and finds the organization

The base URL is https://api.featureflip.io, every path is under /api/v1, and every request sends Authorization: Bearer $FEATUREFLIP_TOKEN.

GET /api/v1/me
GET /api/v1/orgs

The first call confirms the token works (a 401 means it is missing, expired or revoked). The second lists the organizations the token can reach. Use an organization’s key as {org} in every path that follows.

Step 3: use the project that already exists

Every new organization comes with a project keyed default. On the Free plan it has two environments, development and production, and it is the only project the plan allows. Work in it rather than creating a project first:

GET  /api/v1/orgs/{org}/projects
GET  /api/v1/orgs/{org}/projects/default/environments
POST /api/v1/orgs/{org}/projects/default/flags

A new flag starts off in every environment. Turn it on per environment with POST .../flags/{flag}/environments/{env}/toggle and a body of { "enabled": true }. The Quickstart walks through flags, toggles and targeting rules with full request and response bodies.

Step 4: mint an SDK key for the app

The app reads flags with an SDK key, which is a different credential from the API token. The agent can create one per environment:

POST /api/v1/orgs/{org}/projects/default/environments/production/sdk-keys

{ "name": "Checkout service", "type": "ServerSide" }

The plaintext key appears in this response and in no other, so store it straight away, for example as FEATUREFLIP_SDK_KEY in the app’s secret store. A ServerSide key reads every flag in the project and belongs on a backend. Use ClientSide for code that ships to a browser or a phone. The SDK overview shows how each SDK takes the key.

Plan limits the agent will meet

On Free an organization gets one project, two environments per project and ten active flags per project. A create that would go past a cap returns 403 with the error code plan_limit_reached, and the body’s plan_limit names the cap while next_actions suggests a request to make next. Retrying, or retrying with a higher-role token, gets the same answer. Archiving a flag frees its slot.

plan_limit_reached documents the error body, and Plans and Limits lists every plan’s caps.

Machine-readable entry points

An agent that prefers to read a spec over prose can start from any of these:

URL	What it is
/llms.txt	Index of the docs and site, written for language models
/openapi/public-v1.json	OpenAPI 3.0 document for every /api/v1 endpoint
/.well-known/api-onboarding	Plans, credential types and the token-to-SDK-key flow as an API Onboarding Descriptor
/.well-known/apis.json	APIs.json index of both APIs and their specs

Agents that speak MCP

If the agent runs in an MCP client, the @featureflip/mcp server wraps this same API as tools (create_flag, toggle_flag, find_stale_flags and more). It takes the same FEATUREFLIP_TOKEN, so step 1 is identical.