Skip to main content

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​

Step 1: Create a Project in WorkOS​

  1. Log in to the WorkOS Dashboard
  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:

FieldValue
Redirect URIshttps://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:

curl -X POST https://api.ainative.studio/api/v1/auth/providers \
  -H "Authorization: Bearer YOUR_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 ClaimAINative FieldDescription
subuser_idUnique user identifier (e.g. user_01ABC...)
emailemailUser email address
org_idtenantWorkOS Organization ID for multi-tenant isolation

Step 4: Test the Connection​

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

# 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 against AINative
curl -s https://api.ainative.studio/api/v1/auth/verify \
  -H "Authorization: Bearer $TOKEN"

A successful response returns:

{
  "valid": true,
  "provider": "workos",
  "user_id": "user_01ABC123",
  "email": "user@example.com",
  "tenant": "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​

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!"}
    ]
  }'
curl -X POST https://api.ainative.studio/api/v1/zerodb/vectors/search \
  -H "Authorization: Bearer WORKOS_USER_JWT" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "enterprise SSO configuration",
    "top_k": 5
  }'

ZeroMemory Store​

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.

curl -X POST https://api.ainative.studio/api/v1/zerodb/projects/YOUR_PROJECT_ID/rls \
  -H "Authorization: Bearer YOUR_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 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:

curl -X POST https://api.ainative.studio/api/v1/auth/providers/workos/webhooks \
  -H "Authorization: Bearer YOUR_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:

{
  "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​

IssueCauseFix
401 UnauthorizedToken expired or client ID mismatchVerify the client_id matches your WorkOS environment
403 ForbiddenRLS blocking access or org mismatchCheck org_id claim matches the tenant in AINative
invalid_token errorJWKS URI unreachableConfirm the JWKS URL uses the correct client ID
Missing org_id claimUser not in a WorkOS OrganizationEnsure the user authenticated through an organization
SCIM events not receivedWebhook URL misconfiguredVerify the webhook URL is publicly accessible and returns 200

Next Steps​