---
title: "WorkOS"
description: "Integrate WorkOS authentication and SCIM directory sync with AINative Studio APIs and ZeroDB"
canonical: "https://docs.ainative.studio/docs/integrations/workos"
last-updated: "2026-10-22T17:48:46.689Z"
---

# WorkOS

Source: https://docs.ainative.studio/docs/integrations/workos

> Integrate WorkOS authentication and SCIM directory sync with AINative Studio APIs and ZeroDB

## WorkOS Integration

Use WorkOS as your identity provider with AINative Studio. This guide walks through connecting your WorkOS environment so your users can authenticate with WorkOS JWTs and access AINative APIs, ZeroDB, and ZeroMemory. WorkOS also supports SCIM directory sync for automated user provisioning.

---

## Prerequisites

- A [WorkOS account](https://workos.com) with an environment configured
- An [AINative Studio account](https://ainative.studio) with a project and API key
- Your AINative project ID (found in the dashboard under **Settings**)

---

## Step 1: Create a Project in WorkOS

1. Log in to the [WorkOS Dashboard](https://dashboard.workos.com)
2. Navigate to your environment (Staging or Production)
3. Go to **Configuration** and note your:
   - **Client ID** (e.g. `client_01ABC...`)
   - **API Key** (starts with `sk_live_` or `sk_test_`)
4. Under **Redirects**, add your callback URLs
5. Under **Authentication**, enable **AuthKit** or configure SSO connections

WorkOS uses `api.workos.com` as its base API URL.

---

## Step 2: Configure Redirect URIs and SSO Connections

### Redirect URIs

In the WorkOS Dashboard under **Redirects**:

| Field | Value |
|-------|-------|
| **Redirect URIs** | `https://your-app.com/callback`, `http://localhost:3000/callback` |

### SSO Connections (Enterprise)

If your customers use enterprise SSO (Okta, Azure AD, Google Workspace):

1. Go to **Organizations** in the WorkOS Dashboard
2. Create an organization for each customer
3. Set up the SSO connection (SAML or OIDC) for that organization
4. WorkOS handles the federation -- your app receives a standard WorkOS JWT

---

## Step 3: Register WorkOS as an Identity Provider in AINative

Call the AINative API to register your WorkOS environment as a trusted identity provider:

```bash
curl -X POST https://api.ainative.studio/api/v1/auth/providers \
  -H "Authorization: Bearer $AINATIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "workos",
    "domain": "api.workos.com",
    "client_id": "YOUR_WORKOS_CLIENT_ID",
    "jwks_uri": "https://api.workos.com/sso/jwks/YOUR_WORKOS_CLIENT_ID",
    "issuer": "https://api.workos.com",
    "claim_mapping": {
      "user_id": "sub",
      "email": "email",
      "tenant": "org_id"
    }
  }'
```

### Claim Mapping

WorkOS JWTs include these claims that AINative maps automatically:

| WorkOS Claim | AINative Field | Description |
|--------------|----------------|-------------|
| `sub` | `user_id` | Unique user identifier (e.g. `user_01ABC...`) |
| `email` | `email` | User email address |
| `org_id` | `tenant` | WorkOS Organization ID for multi-tenant isolation |

---

## Step 4: Test the Connection

Obtain a test token from WorkOS and verify it works with AINative:

```bash
## Get a session token via AuthKit
## (In production, this happens through the browser redirect flow)
## For testing, use the WorkOS Admin API:
TOKEN=$(curl -s -X POST https://api.workos.com/user_management/authenticate \
  -H "Authorization: Bearer YOUR_WORKOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_WORKOS_CLIENT_ID",
    "grant_type": "authorization_code",
    "code": "AUTH_CODE_FROM_REDIRECT"
  }' | jq -r '.access_token')

## Verify the provider JWT against AINative
## PROVIDER_ID is the id returned when you registered the provider in Step 3.
curl -s -X POST https://api.ainative.studio/api/v1/public/auth-providers/PROVIDER_ID/verify \
  -H "Authorization: Bearer $AINATIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"token\": \"$TOKEN\"}"
```

A successful response returns the decoded claims:

```json
{
  "valid": true,
  "user_id": "user_01ABC123",
  "email": "user@example.com",
  "claims": { "sub": "user_01ABC123", "email": "user@example.com", "org_id": "org_01XYZ789" }
}
```

---

## Step 5: Use WorkOS JWTs with AINative APIs

Once the provider is registered, your users can authenticate with their WorkOS tokens across all AINative services.

### Chat Completions

```bash
curl -X POST https://api.ainative.studio/api/v1/chat/completions \
  -H "Authorization: Bearer WORKOS_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b",
    "messages": [
      {"role": "user", "content": "Hello from WorkOS!"}
    ]
  }'
```

### ZeroDB Vector Search

```bash
curl -X POST https://api.ainative.studio/api/v1/public/YOUR_PROJECT_ID/embeddings/search \
  -H "Authorization: Bearer WORKOS_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "enterprise SSO configuration",
    "limit": 5
  }'
```

### ZeroMemory Store

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/remember \
  -H "Authorization: Bearer WORKOS_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User connected Okta SSO",
    "entity_name": "user_events"
  }'
```

---

## Step 6: Enable Row-Level Security for ZeroDB (Optional)

Row-Level Security (RLS) ensures that each user can only access their own data in ZeroDB. When enabled, the `user_id` claim from the WorkOS JWT is automatically applied as a filter on all queries.

```bash
curl -X POST https://api.ainative.studio/api/v1/zerodb/projects/YOUR_PROJECT_ID/rls \
  -H "Authorization: Bearer $AINATIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "user_id_claim": "sub",
    "policy": "strict"
  }'
```

With RLS enabled:
- **Vectors**: Automatically filtered by the `user_id` extracted from the JWT `sub` claim
- **Tables**: Row-level filtering applied on reads and writes
- **Files**: Users can only access files they uploaded
- **Memory**: Each user gets isolated memory namespaces

---

## SCIM Directory Sync

WorkOS provides [SCIM directory sync](https://workos.com/docs/directory-sync) to automatically provision and deprovision users from enterprise directories (Okta, Azure AD, Google Workspace, etc.).

### Enable Directory Sync

1. In the WorkOS Dashboard, go to **Directory Sync**
2. Create a directory connection for the target organization
3. Configure the SCIM endpoint in your customer's identity provider

### Webhook Events

Configure a webhook endpoint to receive directory sync events from WorkOS:

```bash
curl -X POST https://api.ainative.studio/api/v1/auth/providers/workos/webhooks \
  -H "Authorization: Bearer $AINATIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-app.com/webhooks/workos",
    "events": [
      "dsync.user.created",
      "dsync.user.updated",
      "dsync.user.deleted",
      "dsync.group.created",
      "dsync.group.updated",
      "dsync.group.deleted"
    ]
  }'
```

### Handle User Provisioning

When a user is added to the directory, WorkOS sends a `dsync.user.created` event:

```json
{
  "event": "dsync.user.created",
  "data": {
    "id": "directory_user_01ABC",
    "email": "jane@acme.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "state": "active",
    "raw_attributes": {}
  }
}
```

Use this to auto-create AINative accounts or grant access to ZeroDB projects.

---

## Troubleshooting

| Issue | Cause | Fix |
|-------|-------|-----|
| `401 Unauthorized` | Token expired or client ID mismatch | Verify the `client_id` matches your WorkOS environment |
| `403 Forbidden` | RLS blocking access or org mismatch | Check `org_id` claim matches the tenant in AINative |
| `invalid_token` error | JWKS URI unreachable | Confirm the JWKS URL uses the correct client ID |
| Missing `org_id` claim | User not in a WorkOS Organization | Ensure the user authenticated through an organization |
| SCIM events not received | Webhook URL misconfigured | Verify the webhook URL is publicly accessible and returns 200 |

---

## Next Steps

- [ZeroMemory Guide](/docs/zeromemory/overview) -- Add persistent memory to your WorkOS-authenticated agents
- [API Reference](/docs/api/overview) -- Full API documentation
- [SDK Quick Start](/docs/sdks/overview) -- Client SDKs for React, Next.js, Vue, Svelte, and Python