Authentication & JWT Flow

Authentication in the Flow platform is centered around JSON Web Tokens (JWT) to secure access to the FastAPI backend and maintain user sessions in the Next.js frontend. The system ensures that all requests to sensitive API endpoints are authorized and that user context, such as workspace_id, is correctly associated with every action.

The authentication layer facilitates a multi-tenant environment where users are mapped to specific workspaces. This architecture supports secure document uploads, agent executions, and knowledge management by validating the user's identity and permissions through JWTs passed in the Authorization header.
Sources: README.md:5, AGENTS.md:31, services/api/flow/interfaces/http/routes/golden_sets.py:339-340

Client-Side Authentication Management

The frontend application uses a centralized authentication utility to manage JWTs stored in the browser. Before accessing protected routes like /onboarding or /knowledge, the application checks for the presence of a valid token. If no token is found, the user is redirected to the /login page.

Token Retrieval and Validation

The frontend utilizes a getToken() helper to retrieve the stored JWT. This token is then used to fetch the current user's profile and associated workspaces via the /api/v1/auth/me endpoint.
Sources: apps/web/src/app/(app)/onboarding/page.tsx:59-64, apps/web/src/app/(app)/knowledge/page.tsx:162-167

Authentication Lifecycle Flow

The following diagram illustrates the high-level authentication check performed when a user accesses a protected frontend route.

The application ensures that a user cannot proceed to onboarding or knowledge management without a verified session.
Sources: apps/web/src/app/(app)/onboarding/page.tsx:59-71, apps/web/src/app/(app)/knowledge/page.tsx:162-176

Backend Authorization & Dependencies

The FastAPI backend enforces security through dependency injection. Endpoints require a valid JWT, which is decoded to extract the user_id. This ID is then used to resolve the relevant workspace_id for the request.

Security Implementation Details

The backend infrastructure utilizes get_current_user_id as a dependency for protected routes. For example, the Golden Sets API uses this to ensure that only authenticated users can create or evaluate test sets.

Request Authorization Sequence

The interaction between the client and the secured API endpoints follows a standard Bearer token pattern.

Special Handling for Streaming (SSE)

Flow uses Server-Sent Events (SSE) for streaming agent executions. Because standard browser EventSource APIs do not support custom headers, the platform may pass tokens via query strings for these specific flows.

• Endpoint: /run (streaming)
• Security Note: URL logging of long-lived tokens is identified as a hardening area for future development.
  Sources: AGENTS.md:31-33

Workspace Contextualization

Authentication is intrinsically linked to the workspace system. Every authenticated request eventually resolves to a workspace_id, which is used to filter database queries for agents, documents, and evaluation sets.

async def _get_workspace(repo: FlowRepository, user_id: UUID) -> UUID:
    ws = await repo.list_workspaces_for_user(user_id)
    if ws:
        return ws[0]["id"]
    # Fallback for dev environments
    row = await repo._pool.fetchrow("SELECT id FROM workspaces LIMIT 1")
    return row["id"]

Sources: services/api/flow/interfaces/http/routes/golden_sets.py:339-346

Summary

The Authentication & JWT Flow provides a secure foundation for the Flow platform. By combining client-side token management with robust backend dependencies, the system ensures that user data is isolated by workspace and that all agentic operations—from RAG retrieval to code execution—are performed within an authorized context. Future hardening efforts focus on securing SSE streams and managing token longevity.
Sources: README.md:5, AGENTS.md:33