Skip to main content

​
Overview

WorkOS AuthKit provides SSO and directory sync for enterprise organisations. This guide connects CrewAI Platform to your WorkOS application.
Installing for the first time? Use a Deployment Guide for a complete end-to-end walkthrough including infrastructure setup, a full values.yaml, and post-install steps:

​
Prerequisites

  • WorkOS account at workos.com
  • Admin access to the WorkOS Dashboard

​
Step 1: Create a WorkOS Application

  1. In the WorkOS Dashboard, navigate to Applications
  2. Click Create Application
  3. Enter a name (e.g., CrewAI Platform)
  4. Note the Client ID shown on the application’s main page

​
Step 2: Configure Redirect URI

In your WorkOS Application settings, add a redirect URI: 
https://<APPLICATION_HOST>/auth/workos/callback
Replace <APPLICATION_HOST> with your platform’s hostname (the value you set in envVars.APPLICATION_HOST).

​
Step 3: Note Your AuthKit Domain

  1. In the WorkOS Dashboard, navigate to Developer → Domains
  2. Note your AuthKit domain (e.g., your-org.authkit.app or a custom domain if configured)

​
Step 4: Obtain Your API Key

  1. In the WorkOS Dashboard, go to the main API Keys page
  2. Copy your API key — it starts with sk_live_ (production) or sk_test_ (test environment)

​
Step 5: Configure Helm Values

Both WORKOS_API_KEY and WORKOS_COOKIE_PASSWORD must be placed under envVars:, not secrets:. The chart template has known gaps: secrets.WORKOS_API_KEY is defined in the values schema but never rendered into the pod environment, and secrets.WORKOS_COOKIE_PASSWORD is not in the secrets schema at all. Values placed under secrets: are silently absent from pods, causing WorkOS authentication to fail with no clear error message.After install, verify both keys are present:
kubectl exec -it deploy/crewai-web -- env | grep -E 'WORKOS_API_KEY|WORKOS_COOKIE_PASSWORD'
Generate a cookie password (must be 32 characters or fewer): 
openssl rand -base64 32 | cut -c -32
The openssl rand -base64 32 command produces a 44-character base64 string; the | cut -c -32 suffix truncates it to the required maximum. Omitting the cut step produces a value that WorkOS silently rejects at authentication time. Add to your my-values.yaml: 
envVars:
  AUTH_PROVIDER: "workos"
  WORKOS_CLIENT_ID: "client_..."       # From WorkOS Application main page
  WORKOS_AUTHKIT_DOMAIN: "your-org.authkit.app"  # From Developer > Domains
  WORKOS_COOKIE_PASSWORD: "your-32-char-random-string"  # Max 32 characters
  WORKOS_API_KEY: "sk_live_..."        # From WorkOS API Keys page
WORKOS_COOKIE_PASSWORD is stored as an environment variable (not a Kubernetes Secret) by the chart schema. To avoid committing it to version control, supply it via --set or a separate gitignored values file:
helm upgrade crewai-platform ... --set envVars.WORKOS_COOKIE_PASSWORD="$COOKIE_PWD"
oauth.enabled controls the Built-in Integrations service (Google Workspace, Microsoft 365, HubSpot, etc.) — it is NOT required for WorkOS authentication. WorkOS SSO works without oauth.enabled: true.

​
Combining With Other Features

  • Wharf (trace collection): No additional values needed — Wharf is enabled by default. Ensure the wharf database is pre-created before install. See Wharf reference.
  • Studio V2: Configured entirely post-install via the web UI and kubectl exec commands. No Helm values exist for it. See Enable Studio V2.
  • Built-in Integrations (Google Workspace, Microsoft 365, etc.): Requires oauth.enabled: true and the relevant OAuth credentials. See Built-In Integrations.
  • ArgoCD / GitOps: Auto-generated secrets must be set explicitly. See the ArgoCD guide.

​
Verify Login

After running helm install or helm upgrade, navigate to your platform hostname. You should be redirected to the WorkOS AuthKit login page. If authentication fails, check the web pod logs: 
kubectl logs -l app=crewai-web --tail=50 | grep -i workos