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

# WorkOS SSO

> Configure WorkOS AuthKit as the authentication provider for CrewAI Platform.

## Overview

WorkOS AuthKit provides SSO and directory sync for enterprise organisations. This guide connects CrewAI Platform to your WorkOS application.

<Note>
  **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:

  * [AWS EKS + WorkOS + Wharf + Studio V2](/deployment-guides/aws-workos-wharf-studio)
  * [GCP GKE + WorkOS + Wharf + Studio V2](/deployment-guides/gcp-workos-wharf-studio)
</Note>

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

<Warning>
  **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:

  ```bash theme={null}
  kubectl exec -it deploy/crewai-web -- env | grep -E 'WORKOS_API_KEY|WORKOS_COOKIE_PASSWORD'
  ```
</Warning>

Generate a cookie password (must be 32 characters or fewer):

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

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

<Note>
  `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:

  ```bash theme={null}
  helm upgrade crewai-platform ... --set envVars.WORKOS_COOKIE_PASSWORD="$COOKIE_PWD"
  ```
</Note>

<Note>
  `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`.
</Note>

## 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](/reference/chart-values/wharf).
* **Studio V2**: Configured entirely post-install via the web UI and `kubectl exec` commands. No Helm values exist for it. See [Enable Studio V2](/features/studio-v2).
* **Built-in Integrations** (Google Workspace, Microsoft 365, etc.): Requires `oauth.enabled: true` and the relevant OAuth credentials. See [Built-In Integrations](/features/built-in-integrations-overview).
* **ArgoCD / GitOps**: Auto-generated secrets must be set explicitly. See the [ArgoCD guide](/configuration/argocd).

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

```bash theme={null}
kubectl logs -l app=crewai-web --tail=50 | grep -i workos
```