Skip to main content
Whilst uses WorkOS for authentication, providing SSO, email verification, and organization management.

​
Setup

1

Create a WorkOS account

Sign up at workos.com and create a new project.
2

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)
3

Enable Organizations

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

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';
}