> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whilst.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkOS Authentication

> Set up WorkOS for SSO and email verification

Whilst uses [WorkOS](https://workos.com) for authentication, providing SSO, email verification, and organization management.

## Setup

<Steps>
  <Step title="Create a WorkOS account">
    Sign up at [workos.com](https://workos.com) and create a new project.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Enable Organizations">
    Go to **Organizations** and enable "Allow organization creation via API".
  </Step>

  <Step title="Set environment variables">
    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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:

```bash theme={null}
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:

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