WorkOS Integration

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.

Single Sign-On

SAML and OIDC SSO with 50+ identity providers

Directory Sync

Automatic user provisioning via SCIM

Audit Logs

Enterprise compliance and activity tracking

Prerequisites

Before configuring WorkOS:

Create a WorkOS account at workos.com
Obtain your API Key and Client ID from the WorkOS Dashboard
Configure your redirect URIs in WorkOS

Configuration

Environment Variables

Add these to your environment configuration:

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:

Okta

Azure AD

Google Workspace

OneLogin

JumpCloud

Ping Identity

Auth0

Custom SAML

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.

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

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

SAML 2.0
OIDC

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)

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)

Test the connection
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

Navigate to Admin Portal > Platform Settings > Directory Sync
Click Add Directory
Select your directory provider
Copy the SCIM endpoint URL and bearer token
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

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

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

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

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

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

Security Considerations

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

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

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.

​Overview

Single Sign-On

Directory Sync

Audit Logs

​Prerequisites

​Configuration

​Environment Variables

​Acceptance Criteria

Frontend

Backend / API

Permissions

Business Rules

Error Handling

​Platform Settings

​Acceptance Criteria

Frontend

Backend / API

Permissions

Business Rules

Error Handling

​Single Sign-On (SSO)

​Supported Identity Providers

Okta

Azure AD

Google Workspace

OneLogin

JumpCloud

Ping Identity

Auth0

Custom SAML

​Acceptance Criteria

Frontend

Backend / API

Permissions

Business Rules

Error Handling

​SSO Login Flow

​Acceptance Criteria

Frontend

Backend / API

Permissions

Business Rules

Error Handling

​Configuring SSO for an Organization

​Acceptance Criteria

Frontend

Backend / API

Permissions

Business Rules

Error Handling

​SSO User Attributes

​Acceptance Criteria

Frontend

Backend / API

Permissions

Business Rules

Error Handling

​Directory Sync (SCIM)

​Supported Directories

​Acceptance Criteria

Frontend

Backend / API

Permissions

Business Rules

Error Handling

​SCIM Capabilities

​Acceptance Criteria

Frontend

Backend / API

Permissions

Business Rules

Error Handling

​Configuring Directory Sync

​Acceptance Criteria

Frontend

Backend / API

Permissions

Business Rules

Error Handling

​Attribute Mapping

Overview

Prerequisites

Configuration

Environment Variables

Acceptance Criteria

Platform Settings

Acceptance Criteria

Single Sign-On (SSO)

Supported Identity Providers

Acceptance Criteria

SSO Login Flow

Acceptance Criteria

Configuring SSO for an Organization

Acceptance Criteria

SSO User Attributes

Acceptance Criteria

Directory Sync (SCIM)

Supported Directories

Acceptance Criteria

SCIM Capabilities

Acceptance Criteria

Configuring Directory Sync

Acceptance Criteria

Attribute Mapping

Acceptance Criteria

Group to Role Mapping

Acceptance Criteria

Webhooks

Webhook Events

Acceptance Criteria

Webhook Endpoint

Acceptance Criteria

Webhook Payload Example

Acceptance Criteria

Admin Portal

Generating Admin Portal Link

Acceptance Criteria

Admin Portal Capabilities

Acceptance Criteria

API Reference

Authentication Endpoints

Acceptance Criteria

Directory Sync Endpoints