Authentication¶

Beyond Retrieval v2 uses Clerk for identity management and JWT-based authentication. A bypass mode is available for local development and testing.

Base path: /api/auth

How It Works¶

In production mode the backend verifies Clerk-issued RS256 JWTs using the JWKS (JSON Web Key Sets) endpoint published by Clerk. The JWT sub claim is used as the user_id.

In bypass mode (local development), all requests are attributed to a dev-user identity and no token verification takes place.

Setting	Effect
`BYPASS_AUTH=true`	All requests succeed as `dev-user` (admin)
`BYPASS_AUTH=false` + Clerk keys set	Full JWT verification against Clerk JWKS
No `CLERK_SECRET_KEY`	Bypass mode is implicitly enabled

Local Development

Set BYPASS_AUTH=true in your .env file to skip authentication entirely during development. All admin guards are also bypassed.

GET /api/auth/config¶

Returns the current authentication configuration. Used by the frontend to decide whether to render Clerk sign-in UI or bypass authentication.

Auth: None (public)

RequestResponseErrorscurl ExamplePython Example

Headers:

No headers required. This is a public endpoint.

Status: 200 OK

{
  "success": true,
  "data": {
    "auth_required": true,
    "clerk_publishable_key": "pk_test_..."
  }
}

Field	Type	Description
`auth_required`	boolean	`true` if Clerk auth is enforced, `false` if bypass mode
`clerk_publishable_key`	string	Clerk publishable key for frontend initialization (empty in bypass mode)

This endpoint does not produce errors under normal operation.

Code	Cause
`500`	Server misconfiguration

curl http://localhost:8000/api/auth/config

import httpx

response = httpx.get("http://localhost:8000/api/auth/config")
config = response.json()["data"]

if config["auth_required"]:
    print(f"Clerk key: {config['clerk_publishable_key']}")
else:
    print("Auth bypassed — dev mode")

Token Format¶

When authentication is enabled, include the Clerk JWT in the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

The backend extracts the sub claim from the verified JWT and passes {"user_id": "<sub>", "token": "<raw_jwt>"} to all route handlers.

Role-Based Access¶

User roles are stored in Clerk's public_metadata.role field:

Role	Permissions
`admin`	Full access to all endpoints including notebook management, document ingestion, enhancement, and user management
(default)	Read access to notebooks shared via invite links, chat access

Admin Check in Bypass Mode

When BYPASS_AUTH=true, the dev-user is treated as an admin for all endpoints. No Clerk API calls are made.