Authentication

Flowmanner's two auth surfaces: the browser session cookie and the backend JWT bearer token. What API integrators need to know in minute one.

Two surfaces, by design

Flowmanner intentionally separates browser traffic from API traffic:

Browser surface. The web app authenticates you via a NextAuth session cookie. This cookie fronts Next.js only — the FastAPI backend does not accept it.
Backend surface. Every call to /api/* (missions, chat, evals, …) must carry its own JWT access token as Authorization: Bearer <token>.

The browser obtains that JWT after login and stores it client-side (acquisition chain and caching rules live in frontend/src/lib/get-auth-token.ts). This is why a bare browser fetch with only the session cookie returns 401 against /api/*: the backend never sees or trusts the NextAuth cookie.

Getting a token

POST /api/auth/login
Content-Type: application/json

{ "username_or_email": "you@example.com", "password": "…" }

This endpoint is public (no security declaration in the OpenAPI contract; contracts/openapi.json, op summary "Login"). The response contains an access token and a refresh token.

Access tokens expire after 15 minutes (JWT_ACCESS_TOKEN_EXPIRES: int = 900, backend/backend/app/config.py:33; signing at backend/backend/app/services/auth_service.py:57).
Refresh tokens are longer-lived (backend/backend/app/services/auth_service.py:88) and are used to mint new access tokens without re-login.

Using the token

GET /api/auth/me
Authorization: Bearer <access-token>

Any endpoint whose row shows Bearer in the generated reference tables requires this header. Rows marked public either need no authentication or use a dedicated scheme — notably webhook ingest (POST /api/triggers/webhook/{webhook_path}), which is authenticated by an HMAC-SHA256 X-Signature signature over the raw body instead of a bearer token (backend/backend/app/api/v1/triggers.py:189, verification in backend/backend/app/services/trigger_service.py, verify_webhook_signature).

Common pitfalls

Symptom	Cause	Fix
`401` from `/api/*` despite being logged in in the browser	Only the NextAuth session cookie was sent	Attach `Authorization: Bearer <access-token>`
`GET /api/auth/session` returns null while logged into the API flow	That route reflects the NextAuth session only; the JWT flow does not populate it	Use `POST /api/auth/login` → bearer token for API work
Token worked, then stopped after ~15 min	Access-token TTL elapsed	Mint a fresh one via refresh or re-login

Note: raw schema surfaces (/docs, /redoc, /openapi.json) are gated at the edge and return 404 publicly. This documentation plus the curated /api/v2/openapi.json contract are the intended public references.

Last updated 2026-08-25 (git-derived)

Two surfaces, by design

Flowmanner intentionally separates browser traffic from API traffic:

Browser surface. The web app authenticates you via a NextAuth session cookie. This cookie fronts Next.js only — the FastAPI backend does not accept it.

Backend surface. Every call to /api/* (missions, chat, evals, …) must carry its own JWT access token as Authorization: Bearer <token>.

Getting a token

POST /api/auth/login Content-Type: application/json { "username_or_email": "you@example.com", "password": "…" }

This endpoint is public (no security declaration in the OpenAPI contract; contracts/openapi.json, op summary "Login"). The response contains an access token and a refresh token.

Access tokens expire after 15 minutes (JWT_ACCESS_TOKEN_EXPIRES: int = 900, backend/backend/app/config.py:33; signing at backend/backend/app/services/auth_service.py:57).

Refresh tokens are longer-lived (backend/backend/app/services/auth_service.py:88) and are used to mint new access tokens without re-login.

Using the token

GET /api/auth/me Authorization: Bearer <access-token>

Common pitfalls

Symptom

Cause

Fix

401 from /api/* despite being logged in in the browser

Only the NextAuth session cookie was sent

Attach Authorization: Bearer <access-token>

GET /api/auth/session returns null while logged into the API flow

That route reflects the NextAuth session only; the JWT flow does not populate it

Use POST /api/auth/login → bearer token for API work

Token worked, then stopped after ~15 min

Access-token TTL elapsed

Mint a fresh one via refresh or re-login

Note: raw schema surfaces (/docs, /redoc, /openapi.json) are gated at the edge and return 404 publicly. This documentation plus the curated /api/v2/openapi.json contract are the intended public references.

Last updated 2026-08-25 (git-derived)