WorkOS Authentication

Whilst uses WorkOS for authentication, providing SSO, email verification, and organization management.

Setup

Create a WorkOS account

Configure your application

In the WorkOS Dashboard:

Go to Applications → Create a new application
Add redirect URI: http://127.0.0.1:3000/api/auth/workos/callback (local dev)
Add redirect URI: https://app.whilst.io/api/auth/workos/callback (production)

Enable Organizations

Go to Organizations and enable “Allow organization creation via API”.

Set environment variables

WORKOS_API_KEY=sk_test_your_key_here
WORKOS_CLIENT_ID=client_your_id_here
WORKOS_REDIRECT_URI=http://127.0.0.1:3000/api/auth/workos/callback

In production redirect URIs, HTTP protocol can only be used with the IP address 127.0.0.1. All other production URIs must use HTTPS.

Auth Flow

User clicks "Sign Up" or "Log In"
    ↓
Redirect to WorkOS authorization URL
    ↓
WorkOS handles email verification / SSO
    ↓
Redirect back to /api/auth/workos/callback
    ↓
Create/update session cookie (whilst_session)
    ↓
Redirect to workspace dashboard

Testing

Run the WorkOS test script to verify your configuration:

cd apps/web-app
pnpm tsx scripts/test-workos.ts

Expected output:

🔧 WorkOS Configuration:
   API Key: sk_test_xxxx...
   Client ID: client_xxxxx

📋 Test 1: Create Organization
   ✅ SUCCESS: Organization created

🔐 Test 2: Generate Authorization URL
   ✅ SUCCESS: Authorization URL generated

Session Structure

After authentication, the session contains:

interface Session {
  userId: string;      // UUID
  accountId: string;   // Workspace/tenant UUID
  email: string;
  role: 'admin' | 'member' | 'viewer';
}

Getting Started

Features

Guides

Development

WorkOS Authentication

Setup

Auth Flow

Testing

Session Structure

​Setup

​Auth Flow

​Testing

​Session Structure

Setup

Auth Flow

Testing

Session Structure