Authentication Method: WorkOS session-based authentication with secure cookies
CORS: Configured by the CORS_ALLOWED_ORIGINS
allowlist with credentials support
Frontend Auth Flow:
- Send
credentials: 'include'on authenticated requests. -
Fetch a CSRF token after login:
GET /auth/csrf(store and reuse it). -
Send
X-CSRF-Tokenon all state-changing requests (POST/PUT/PATCH/DELETE). -
Auto-refresh happens on authenticated requests; you can also call
POST /auth/refresh. - On 401, redirect to login; on 403, show "forbidden".
-
Login:
POST /auth/login→ if 409, callPOST /auth/select-organization. - Logout:
POST /auth/logoutclears the session cookie.
POST
/auth/login
Authenticate user with email and password
Request Body:
{
"email": "user@example.com",
"password": "password123"
}Response (200):
(empty body)Response (409):
{
"success": false,
"code": "organization_selection_required",
"pendingAuthenticationToken": "pat_123",
"organizations": [
{ "id": "org_123", "name": "Acme Co" }
],
"error": "The user must choose an organization to finish their authentication."
}
Sets Cookie: wos-session (httpOnly, secure),
wos-csrf
POST
/auth/select-organization
Complete login after user selects an organization
Request Body:
{
"pendingAuthenticationToken": "pat_123",
"organizationId": "org_123"
}Response (200):
(empty body)
Sets Cookie: wos-session (httpOnly, secure),
wos-csrf
POST
/auth/refresh
Refresh the current WorkOS session
Headers:
X-CSRF-Token: <token>Response (200):
{
"success": true,
"csrfToken": "token"
}
Sets Cookie: wos-session (httpOnly, secure),
wos-csrf
GET
/auth/csrf
Issue a CSRF token for the current session
Response (200):
{
"csrfToken": "token"
}Sets Cookie: wos-csrf
POST
/auth/logout
Log out current user and clear session
Headers:
X-CSRF-Token: <token>Response:
{
"success": false,
"error": null
}Clears Cookie: wos-session, wos-csrf
GET
/auth/callback
OAuth callback for WorkOS authentication flow
Query Parameters:
code (required) - Authorization code from WorkOS
Response: Redirect to / with session cookie