> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkOS Integration

> Enterprise authentication with SSO, SCIM directory sync, and audit logs

## Overview

WorkOS provides enterprise-ready authentication features including Single Sign-On (SSO), Directory Sync (SCIM), and Admin Portal capabilities. This integration enables MemberPulse to support enterprise clients with existing identity providers.

<CardGroup cols={3}>
  <Card title="Single Sign-On" icon="key">
    SAML and OIDC SSO with 50+ identity providers
  </Card>

  <Card title="Directory Sync" icon="users">
    Automatic user provisioning via SCIM
  </Card>

  <Card title="Audit Logs" icon="clipboard-list">
    Enterprise compliance and activity tracking
  </Card>
</CardGroup>

***

## Prerequisites

Before configuring WorkOS:

1. Create a WorkOS account at [workos.com](https://workos.com)
2. Obtain your API Key and Client ID from the WorkOS Dashboard
3. Configure your redirect URIs in WorkOS

***

## Configuration

### Environment Variables

Add these to your environment configuration:

```bash theme={null}
WORKOS_API_KEY=sk_live_xxxxxxxxxxxx
WORKOS_CLIENT_ID=client_xxxxxxxxxxxx
WORKOS_REDIRECT_URI=https://app.memberpulse.com/auth/callback/workos
WORKOS_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx
```

#### Acceptance Criteria

##### Frontend

* [ ] Environment Variables workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Environment Variables as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Platform Settings

Navigate to **Admin Portal > Platform Settings > Integrations > WorkOS**

| Setting            | Type   | Required | Description                        |
| ------------------ | ------ | -------- | ---------------------------------- |
| API Key            | Secret | Yes      | WorkOS API key (starts with `sk_`) |
| Client ID          | Text   | Yes      | WorkOS Client ID                   |
| Redirect URI       | URL    | Yes      | OAuth callback URL                 |
| Webhook Secret     | Secret | Yes      | Webhook signing secret             |
| Default Connection | Select | No       | Default SSO connection for login   |

***

#### Acceptance Criteria

##### Frontend

* [ ] Platform Settings workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Platform Settings as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

## Single Sign-On (SSO)

### Supported Identity Providers

WorkOS SSO supports 50+ identity providers including:

<CardGroup cols={4}>
  <Card title="Okta" icon="circle-check" />

  <Card title="Azure AD" icon="circle-check" />

  <Card title="Google Workspace" icon="circle-check" />

  <Card title="OneLogin" icon="circle-check" />

  <Card title="JumpCloud" icon="circle-check" />

  <Card title="Ping Identity" icon="circle-check" />

  <Card title="Auth0" icon="circle-check" />

  <Card title="Custom SAML" icon="circle-check" />
</CardGroup>

#### Acceptance Criteria

##### Frontend

* [ ] Supported Identity Providers workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Supported Identity Providers as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### SSO Login Flow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant MemberPulse
    participant WorkOS
    participant IdP as Identity Provider

    User->>MemberPulse: Click "Sign in with SSO"
    MemberPulse->>WorkOS: Get Authorization URL
    WorkOS-->>MemberPulse: Return URL
    MemberPulse->>User: Redirect to IdP
    User->>IdP: Authenticate
    IdP->>WorkOS: SAML/OIDC Response
    WorkOS->>MemberPulse: Callback with code
    MemberPulse->>WorkOS: Exchange code for profile
    WorkOS-->>MemberPulse: User profile
    MemberPulse->>User: Create session, redirect to app
```

#### Acceptance Criteria

##### Frontend

* [ ] SSO Login Flow workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports SSO Login Flow as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Configuring SSO for an Organization

1. Navigate to **Client Portal > Settings > Authentication**
2. Click **Configure SSO**
3. Select identity provider type (SAML 2.0 or OIDC)
4. Enter connection details provided by your IdP:

<Tabs>
  <Tab title="SAML 2.0">
    | Field           | Description                                            |
    | --------------- | ------------------------------------------------------ |
    | IdP Entity ID   | Identity Provider's Entity ID                          |
    | IdP SSO URL     | Single Sign-On URL                                     |
    | IdP Certificate | X.509 Certificate (PEM format)                         |
    | SP Entity ID    | `https://api.workos.com/sso/saml/...` (auto-generated) |
    | SP ACS URL      | Assertion Consumer Service URL (auto-generated)        |
  </Tab>

  <Tab title="OIDC">
    | Field         | Description                            |
    | ------------- | -------------------------------------- |
    | Client ID     | OIDC Client ID from IdP                |
    | Client Secret | OIDC Client Secret                     |
    | Discovery URL | `.well-known/openid-configuration` URL |
    | Redirect URI  | Callback URL (auto-generated)          |
  </Tab>
</Tabs>

5. Test the connection
6. Enable SSO for users

#### Acceptance Criteria

##### Frontend

* [ ] Configuring SSO for an Organization workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Configuring SSO for an Organization as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### SSO User Attributes

Map IdP attributes to MemberPulse user fields:

| IdP Attribute               | MemberPulse Field | Required |
| --------------------------- | ----------------- | -------- |
| `email`                     | Email             | Yes      |
| `given_name` or `firstName` | First Name        | Yes      |
| `family_name` or `lastName` | Last Name         | Yes      |
| `groups`                    | Roles             | No       |
| `department`                | Department        | No       |
| `job_title`                 | Job Title         | No       |

***

#### Acceptance Criteria

##### Frontend

* [ ] SSO User Attributes workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports SSO User Attributes as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

## Directory Sync (SCIM)

Automatically provision and deprovision users based on your identity provider's directory.

### Supported Directories

* Okta
* Azure AD (Entra ID)
* Google Workspace
* OneLogin
* JumpCloud
* Generic SCIM 2.0

#### Acceptance Criteria

##### Frontend

* [ ] Supported Directories workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Supported Directories as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### SCIM Capabilities

| Operation       | Supported | Description                                 |
| --------------- | --------- | ------------------------------------------- |
| Create User     | Yes       | New users in IdP are created in MemberPulse |
| Update User     | Yes       | Profile changes sync automatically          |
| Deactivate User | Yes       | Removed users are deactivated               |
| Delete User     | Yes       | Optionally hard-delete removed users        |
| Create Group    | Yes       | IdP groups sync as MemberPulse roles        |
| Update Group    | Yes       | Group membership changes sync               |
| Delete Group    | Yes       | Removed groups are deleted                  |

#### Acceptance Criteria

##### Frontend

* [ ] SCIM Capabilities workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports SCIM Capabilities as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Configuring Directory Sync

1. Navigate to **Admin Portal > Platform Settings > Directory Sync**
2. Click **Add Directory**
3. Select your directory provider
4. Copy the SCIM endpoint URL and bearer token
5. Configure SCIM provisioning in your IdP using these credentials

**SCIM Endpoint:** `https://api.workos.com/directories/{directory_id}/scim/v2`

#### Acceptance Criteria

##### Frontend

* [ ] Configuring Directory Sync workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Configuring Directory Sync as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Attribute Mapping

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "user@example.com",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "user@example.com"
    }
  ],
  "active": true,
  "groups": [
    {
      "value": "group_123",
      "display": "Engineering"
    }
  ]
}
```

#### Acceptance Criteria

##### Frontend

* [ ] Attribute Mapping workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Attribute Mapping as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Group to Role Mapping

Map directory groups to MemberPulse roles:

| Directory Group       | MemberPulse Role    |
| --------------------- | ------------------- |
| `MemberPulse Admins`  | `ROLE_CLIENT_ADMIN` |
| `MemberPulse Staff`   | `ROLE_CLIENT_USER`  |
| `MemberPulse Members` | `ROLE_MEMBER`       |

***

#### Acceptance Criteria

##### Frontend

* [ ] Group to Role Mapping workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Group to Role Mapping as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

## Webhooks

WorkOS sends webhooks for real-time event notifications.

### Webhook Events

| Event                    | Description                   |
| ------------------------ | ----------------------------- |
| `dsync.user.created`     | New user provisioned via SCIM |
| `dsync.user.updated`     | User profile updated          |
| `dsync.user.deleted`     | User deprovisioned            |
| `dsync.group.created`    | New group created             |
| `dsync.group.updated`    | Group membership changed      |
| `dsync.group.deleted`    | Group removed                 |
| `connection.activated`   | SSO connection activated      |
| `connection.deactivated` | SSO connection deactivated    |

#### Acceptance Criteria

##### Frontend

* [ ] Webhook Events workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Webhook Events as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Webhook Endpoint

Configure in WorkOS Dashboard:

```
POST https://api.memberpulse.com/webhooks/workos
```

#### Acceptance Criteria

##### Frontend

* [ ] Webhook Endpoint workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Webhook Endpoint as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Webhook Payload Example

```json theme={null}
{
  "id": "event_01234567890",
  "event": "dsync.user.created",
  "data": {
    "id": "directory_user_01234567890",
    "directory_id": "directory_01234567890",
    "emails": [
      {
        "primary": true,
        "value": "user@example.com"
      }
    ],
    "first_name": "John",
    "last_name": "Doe",
    "state": "active",
    "raw_attributes": {}
  }
}
```

***

#### Acceptance Criteria

##### Frontend

* [ ] Webhook Payload Example workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Webhook Payload Example as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

## Admin Portal

WorkOS Admin Portal allows enterprise clients to self-manage their SSO and Directory Sync configurations.

### Generating Admin Portal Link

```php theme={null}
// Generate a short-lived admin portal link
$link = $workos->portal->generateLink([
    'organization' => 'org_01234567890',
    'intent' => 'sso', // or 'dsync'
    'return_url' => 'https://app.memberpulse.com/settings'
]);
```

#### Acceptance Criteria

##### Frontend

* [ ] Generating Admin Portal Link workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Generating Admin Portal Link as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Admin Portal Capabilities

* Configure SSO connections
* Upload IdP metadata/certificates
* Test SSO connections
* Configure directory sync
* View sync logs and errors

***

#### Acceptance Criteria

##### Frontend

* [ ] Admin Portal Capabilities workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Admin Portal Capabilities as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

## API Reference

### Authentication Endpoints

```
GET  /auth/sso                        # Initiate SSO login
GET  /auth/callback/workos            # SSO callback handler
POST /api/auth/sso/connections        # List SSO connections
POST /api/auth/sso/connections/{id}   # Get connection details
```

#### Acceptance Criteria

##### Frontend

* [ ] Authentication Endpoints workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Authentication Endpoints as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Directory Sync Endpoints

```
GET  /api/directories                 # List directories
GET  /api/directories/{id}            # Get directory details
GET  /api/directories/{id}/users      # List directory users
GET  /api/directories/{id}/groups     # List directory groups
POST /api/directories/{id}/sync       # Trigger manual sync
```

***

#### Acceptance Criteria

##### Frontend

* [ ] Directory Sync Endpoints workflow is implemented in the UI as described.

##### Backend / API

* [ ] Backend behavior supports Directory Sync Endpoints as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

## Troubleshooting

<AccordionGroup>
  <Accordion title="SSO login fails with 'Invalid connection'">
    * Verify the SSO connection is activated in WorkOS Dashboard
    * Check that the organization has the correct connection ID
    * Ensure redirect URIs match exactly
  </Accordion>

  <Accordion title="Users not syncing from directory">
    * Verify SCIM endpoint and bearer token in IdP
    * Check WorkOS Dashboard for sync errors
    * Ensure users are assigned to the correct groups in IdP
    * Check attribute mapping configuration
  </Accordion>

  <Accordion title="Webhook events not received">
    * Verify webhook URL is accessible from internet
    * Check webhook secret is configured correctly
    * Review webhook logs in WorkOS Dashboard
    * Ensure firewall allows WorkOS IP addresses
  </Accordion>
</AccordionGroup>

***

## Security Considerations

<Warning>
  Never expose your WorkOS API key in client-side code. All WorkOS API calls should be made from the backend.
</Warning>

* Store API keys in secure environment variables
* Validate webhook signatures before processing
* Use HTTPS for all callback URLs
* Regularly rotate API keys
* Monitor audit logs for suspicious activity

## Features

### WorkOS Integration

#### Acceptance Criteria

##### Frontend

* [ ] UI provides configuration controls and status/health indicators for this integration.

##### Backend / API

* [ ] Integration can be connected, configured, and exercised end-to-end (auth + sync/webhooks).

##### Permissions

* [ ] Only `ROLE_CLIENT_ADMIN` (or equivalent) can configure the integration.

##### Business Rules

* [ ] Data sync respects tenant isolation and mapping rules.

##### Error Handling

* [ ] Auth and sync failures are surfaced with actionable messages and retry behavior.