WorkOS Configuration

This guide walks you through the complete WorkOS setup process, from creating an account to configuring authentication for Hazel Chat.

Prerequisites

Before you begin, ensure you have:

A WorkOS account (free for development)
Access to the WorkOS Dashboard
Hazel Chat source code cloned locally

Overview

WorkOS AuthKit provides enterprise-ready authentication with:

Multi-provider auth - Email/password, Google, GitHub, Microsoft, and more
Enterprise SSO - SAML and OIDC support
Organization management - Multi-tenant with role-based access
Session management - Secure JWT tokens
MFA support - Two-factor authentication

Step-by-Step Setup

1. Create a WorkOS Account

Go to workos.com and create a free account.

WorkOS offers a free tier for development with unlimited users.

Create your organization

After signing up, create your organization in the WorkOS dashboard.

Access your dashboard

Navigate to dashboard.workos.com to configure your application.

2. Enable AuthKit

AuthKit is WorkOS’s managed authentication solution.

Navigate to AuthKit

In the WorkOS dashboard, go to Authentication → AuthKit.

Enable AuthKit

Click “Get started” or “Enable AuthKit” if not already enabled.

Configure your app

Set your application name and branding:

App Name: Hazel Chat (or your preferred name)
Logo: Optional - upload your logo
Primary Color: Optional - customize the auth UI

Enable sign-in methods

Choose at least one authentication method:Recommended for development:

✅ Email + Password
✅ Google OAuth
✅ GitHub OAuth

Optional:

Microsoft
Magic Links
Apple
LinkedIn

You can enable additional sign-in methods later. Email + Password is sufficient to get started.

3. Configure Redirect URIs

Redirect URIs tell WorkOS where to send users after authentication.

Navigate to Redirects

In the WorkOS dashboard, go to Redirects → Edit redirect URIs.

Add development redirect URI

Add the backend callback URL for local development:

http://localhost:3003/auth/callback

This is the backend redirect URI, not the frontend URL.

Add production redirect URI (when ready)

When deploying to production, add your production callback URL:

https://api.example.com/auth/callback

Replace api.example.com with your actual backend domain.

Save changes

Click Save to apply the redirect URI configuration.

4. Create Required Roles

Hazel Chat uses custom roles for organization access control.

Navigate to Roles

In the WorkOS dashboard, go to Roles.

Create Owner role

Click “Create Role” and configure:

Role Slug: owner
Name: Owner
Description: Full access, can delete organization

Click Create.

Create Admin role

Create another role:

Role Slug: admin
Name: Admin
Description: Can manage members and settings

Click Create.

Create Member role

Create the default role:

Role Slug: member
Name: Member
Description: Standard access (default)

Click Create.

These role slugs (owner, admin, member) are hardcoded in Hazel Chat. They must match exactly.

Role Permissions Matrix

Role	Delete Org	Manage Members	Manage Settings	Channel Access
Owner	✅	✅	✅	✅
Admin	❌	✅	✅	✅
Member	❌	❌	❌	✅

5. Get API Credentials

Retrieve your API credentials from the WorkOS dashboard.

Get API Key

Go to API Keys in the dashboard.Copy your API Key:

Development: sk_test_...
Production: sk_live_...

Never commit API keys to git. Store them in .env files only.

Get Client ID

In the Configuration section, copy your Client ID:

client_01ABCDEF123456

Get Webhook Secret (optional)

If using webhooks, go to Webhooks and copy the Webhook Secret:

whs_abc123...

6. Configure Environment Variables

Add WorkOS credentials to your environment files.

# WorkOS Authentication
WORKOS_API_KEY=sk_test_your_api_key_here
WORKOS_CLIENT_ID=client_01ABCDEF123456
WORKOS_REDIRECT_URI=http://localhost:3003/auth/callback
WORKOS_COOKIE_DOMAIN=localhost
WORKOS_WEBHOOK_SECRET=whs_your_webhook_secret

The frontend redirect URI is different from the backend. The frontend receives the code and exchanges it via the backend.

7. Test Authentication

Verify your WorkOS configuration is working.

Start development services

# Start Docker services
docker compose up -d

# Start application
bun run dev

Open the application

Navigate to http://localhost:3000

Click Sign In

Click the Sign In button to start the authentication flow.

Complete authentication

Verify user creation

Check that the user was created in your database:

cd packages/db
bun run db:studio

Open http://localhost:4983 and check the users table.

Production Configuration

Update Redirect URIs

When deploying to production:

Add production redirect URI

In WorkOS dashboard → Redirects, add:

https://api.example.com/auth/callback

Update environment variables

apps/backend/.env.production

WORKOS_API_KEY=sk_live_your_production_key
WORKOS_CLIENT_ID=client_01ABCDEF123456
WORKOS_REDIRECT_URI=https://api.example.com/auth/callback
WORKOS_COOKIE_DOMAIN=example.com

Enable production API key

In WorkOS dashboard → API Keys, switch to using the Production API Key (sk_live_...).

Configure Custom Domain (Optional)

Customize the authentication URL:

Go to Custom Domains

In WorkOS dashboard → Custom Domains

Add your domain

Configure auth.example.com to brand the authentication flow.

Verify DNS

Add the required DNS records to verify ownership.

Webhooks (Optional)

Set up webhooks to receive events from WorkOS.

Navigate to Webhooks

Go to Webhooks in the WorkOS dashboard.

Add webhook endpoint

Configure your webhook URL:

https://api.example.com/webhooks/workos

Select events

Subscribe to relevant events:

user.created
user.updated
user.deleted
organization_membership.created
organization_membership.deleted

Copy webhook secret

Save the webhook secret to your environment:

WORKOS_WEBHOOK_SECRET=whs_abc123...

Multi-Organization Setup

Creating Organizations

Users can belong to multiple organizations:

Create organization via API

Organizations are typically created when users sign up:

const org = await workos.organizations.createOrganization({
  name: "ACME Corp",
  externalId: uuid(), // Your internal org ID
  allowProfilesOutsideOrganization: false
})

Add members

Add users to organizations with roles:

await workos.organizationMemberships.createOrganizationMembership({
  organizationId: org.id,
  userId: user.id,
  roleSlug: "member"
})

Organization Switching

Users can switch between organizations:

// Login with specific organization
window.location.href = `${BACKEND_URL}/auth/login?organizationId=${orgId}`

Troubleshooting

Redirect URI mismatch error

Error: redirect_uri_mismatchSolution: Verify the redirect URI in your .env file matches exactly what’s configured in WorkOS dashboard:

# Check backend redirect URI
echo $WORKOS_REDIRECT_URI

# Should match WorkOS dashboard → Redirects
http://localhost:3003/auth/callback

Invalid client ID error

Error: invalid_clientSolution: Verify your WORKOS_CLIENT_ID is correct:

echo $WORKOS_CLIENT_ID
# Should start with: client_

Copy the correct value from WorkOS dashboard → Configuration.

API key authentication fails

Error: Unauthorized or Invalid API keySolution: Check you’re using the correct API key for your environment:

# Development
WORKOS_API_KEY=sk_test_...

# Production
WORKOS_API_KEY=sk_live_...

Never mix development and production keys.

Role not found error

Error: Role 'owner' not foundSolution: Create all three required roles in WorkOS dashboard → Roles:

owner
admin
member

The role slug must match exactly (case-sensitive).

User not syncing to database

Error: User authenticates but doesn’t appear in databaseSolution: Check backend logs for errors:

# View backend logs
cd apps/backend
bun run dev

Verify DATABASE_URL is correct and database is accessible.

Security Best Practices

Follow these security guidelines in production:

API Keys

Never commit API keys

API keys should never be committed to git. Always use .env files.

# ✅ Correct
WORKOS_API_KEY=sk_test_...

# ❌ Wrong - hardcoded in source
const apiKey = "sk_test_abc123"

Use different keys per environment

Development and production must use separate API keys:

Development: sk_test_...
Production: sk_live_...

Rotate keys regularly

Rotate API keys every 90 days for security.

Restrict key access

Limit who can access production API keys.

Redirect URIs

Use HTTPS in production

# ✅ Production
WORKOS_REDIRECT_URI=https://api.example.com/auth/callback

# ❌ Production (insecure)
WORKOS_REDIRECT_URI=http://api.example.com/auth/callback

Whitelist exact URIs

Only add the specific redirect URIs you need. Don’t use wildcards.

Validate state parameter

The state parameter is validated automatically by Hazel Chat to prevent CSRF.

# Development
WORKOS_COOKIE_DOMAIN=localhost

# Production
WORKOS_COOKIE_DOMAIN=example.com  # Your root domain

Advanced Configuration

Custom Email Templates

Customize authentication emails:

Go to WorkOS dashboard → Email Templates
Edit templates for:
- Welcome emails
- Password reset
- Email verification
- Magic links

MFA Setup

Enable multi-factor authentication:

Go to Authentication → MFA
Enable MFA options:
- SMS
- Authenticator apps (TOTP)
- WebAuthn

Session Duration

Configure session expiration:

Go to Authentication → Session Settings
Set session duration (default: 7 days)
Configure refresh token expiration

Next Steps

Authentication Guide

Learn about the authentication flow

Environment Variables

Complete configuration reference

Deployment

Deploy to production

Database Setup

Set up PostgreSQL

Get Started

Core Features

Guides

Integrations

Architecture

WorkOS Configuration

Prerequisites

Overview

Step-by-Step Setup

1. Create a WorkOS Account

2. Enable AuthKit

3. Configure Redirect URIs

4. Create Required Roles

Role Permissions Matrix

5. Get API Credentials

6. Configure Environment Variables

7. Test Authentication

Production Configuration

Update Redirect URIs

Configure Custom Domain (Optional)

Webhooks (Optional)

Multi-Organization Setup

Creating Organizations

Organization Switching

Troubleshooting

Security Best Practices

API Keys

Redirect URIs

Advanced Configuration

Custom Email Templates

MFA Setup

Session Duration

Next Steps

Authentication Guide

Environment Variables

Deployment

Database Setup

Additional Resources

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Integrations

Architecture

​Prerequisites

​Overview

​Step-by-Step Setup

​1. Create a WorkOS Account

​2. Enable AuthKit

​3. Configure Redirect URIs

​4. Create Required Roles

​Role Permissions Matrix

​5. Get API Credentials

​6. Configure Environment Variables

​7. Test Authentication

​Production Configuration

​Update Redirect URIs

​Configure Custom Domain (Optional)

​Webhooks (Optional)

​Multi-Organization Setup

​Creating Organizations

​Organization Switching

​Troubleshooting

​Security Best Practices

​API Keys

​Redirect URIs

​Cookie Security

​Advanced Configuration

​Custom Email Templates

​MFA Setup

​Session Duration

​Next Steps

Authentication Guide

Environment Variables

Deployment

Database Setup

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Overview

Step-by-Step Setup

1. Create a WorkOS Account

2. Enable AuthKit

3. Configure Redirect URIs

4. Create Required Roles

Role Permissions Matrix

5. Get API Credentials

6. Configure Environment Variables

7. Test Authentication

Production Configuration

Update Redirect URIs

Configure Custom Domain (Optional)

Webhooks (Optional)

Multi-Organization Setup

Creating Organizations

Organization Switching

Troubleshooting

Security Best Practices

API Keys

Redirect URIs

Cookie Security

Advanced Configuration

Custom Email Templates

MFA Setup

Session Duration

Next Steps

Additional Resources