API Overview
FlagPulse exposes a JSON REST API under three base paths, each with a different auth model.
| Base path | Auth | Used by |
|---|---|---|
/api/auth | none (issues the session) | Dashboard login/register |
/api/projects, /api/environments, /api/flags | JWT cookie (verifyUser) | Dashboard, management scripts |
/api/v1 (SDK) and /api/v1/stream (SSE) | SDK key | Your application at runtime |
Authentication
Dashboard/management routes use a JWT stored in an httpOnly cookie named token, set by /api/auth/login or /api/auth/register. Include credentials on every request (credentials: "include" / withCredentials: true) — there is no bearer-token alternative for these routes.
Requests to project-scoped routes also expect an X-FlagPulse-Project-Id header carrying the current project's ID. It's used for audit-log attribution; the dashboard's Axios client attaches it automatically from Redux state.
SDK/SSE routes are not JWT-protected at all — they're authenticated by an environment's SDK key, sent as the x-sdk-key header (SDK routes) or an sdkKey query parameter (SSE). See Auth and SDK Quickstart.
Errors
Errors are JSON with a consistent shape:
{
"success": false,
"message": "Invalid environment id"
}5xx errors always return the generic message "Internal server Error" regardless of the underlying cause (the real error is logged server-side only). 4xx errors return the specific message thrown.
Common status codes:
| Code | Meaning |
|---|---|
400 | Malformed input (e.g. not a valid UUID, missing required field) |
401 | Missing/invalid JWT cookie, or missing/invalid SDK key |
404 | Resource not found |
500 | Unhandled server error |
IDs
Every project, environment, and flag ID is a Postgres-generated UUID (gen_random_uuid()). Route params are validated against a UUID regex before hitting the database, so a malformed ID returns 400 rather than a database error.
Sections
- Auth — register, login, logout
- Projects — projects, their environments, flags, and audit logs
- Environments — SDK key rotation, listing flags
- Flags — editing, toggling, deleting, and flag-level audit history