Start Here

Authentication

Authenticate REST API requests with server and client Bearer API keys

Authentication

FlagForge authenticates API requests with an API key sent as a Bearer token. Use a server key for control-plane management and a client key for flag evaluation and SDK configuration bootstrap.

The health endpoint and OpenAPI endpoints do not require authentication. Other endpoints use the authorization rules described below.

Choose an API key

Credential	Prefix	Use	Project scope
Global server key	`srv_`	Manage resources across projects and evaluate flags	Global when the key has no project scope
Project-scoped server key	`srv_`	Manage resources for one project and evaluate flags	Limited to its associated project
Client key	`cli_`	Call evaluation and configuration endpoints	Must be scoped to a project

Server keys authorize management endpoints for projects, environments, flags, segments, webhooks, and audit logs. Client keys authorize evaluation endpoints for their own project. Server keys can also call evaluation endpoints.

The API does not expose a credential-issuance endpoint. In a local self-hosted setup, the database-seeding workflow prints server and client API keys for the operator. Keep those keys secret and provide application code only the key type it requires.

Note:

Never expose a server key in a browser, client-side bundle, or other untrusted environment. Use a client key for application evaluation and keep it scoped to the intended project.

Send the Bearer token

Set the Authorization header in this form:

http

Authorization: Bearer <api-key>

Use a server key to list projects:

bash

curl http://localhost:4000/v1/projects \
  -H "Authorization: Bearer $FLAGFORGE_SERVER_KEY"

Use a client key to bootstrap flag definitions for the SDK:

bash

curl http://localhost:4000/v1/config \
  -H "Authorization: Bearer $FLAGFORGE_CLIENT_KEY"

The value after Bearer must be the complete API key. Do not send only the srv_ or cli_ prefix.

Authorization by endpoint

Endpoint group	Required credential	Authorization behavior
Project and resource management under `/v1/projects`	Server key	A global server key may act on any project. A project-scoped server key may act only on its associated project.
`POST /v1/evaluate`	Client key or server key	Client keys evaluate within their project; server keys are also allowed.
`GET /v1/config`	Client key or server key	Client keys must be project-scoped; server keys are also allowed.
`GET /v1/flags/:flagKey/eval`	Client key or server key	Client keys evaluate within their project; server keys are also allowed.
`GET /health`	None	Provides liveness and a database check.
`GET /docs` and `GET /openapi.json`	None	Provides the interactive Swagger UI and the generated OpenAPI document.

A project-scoped server key cannot access another project's resources. If its project does not match the projectId in a project-scoped route, the request is rejected.

Authentication failures

Requests without an Authorization header, requests whose header is not in the Bearer <api-key> form, and requests with an unknown token are rejected. The API reports these cases with the following messages:

Situation	Message
Missing or malformed header	`Missing or malformed Authorization header. Expected: Bearer <api-key>.`
Unknown token	`Invalid API key.`
Client key used for management	`A server API key is required for management endpoints.`
Client key without a project scope	`Client keys must be scoped to a project.`
Project-scoped server key used for another project	`This API key is not authorized for the requested project.`

API errors use a uniform envelope:

json

{
  "error": {
    "code": "error_code",
    "message": "Invalid API key."
  }
}

The API distinguishes authentication failures from authorization failures, but the available API evidence does not specify the HTTP status codes for these responses. Use the code and message fields to identify the failure, and consult the live OpenAPI contract for the deployed service.

Discover the live security contract

After starting the API, open http://localhost:4000/docs to inspect the interactive contract or fetch http://localhost:4000/openapi.json for the raw OpenAPI document.

The OpenAPI specification declares a Bearer HTTP security scheme named bearerAuth. It describes server keys with the srv_ prefix and client keys with the cli_ prefix.

API overview

Explore the available management and evaluation resources.

Bootstrap flag config

Fetch flag definitions for local SDK evaluation.

Evaluate all flags

Evaluate flags for an application evaluation context.

PreviousREST API NextHealth