How to Integrate WorkOS with Your Headless CMS
Connect WorkOS to your headless CMS so enterprise SSO, Directory Sync instructions, tenant settings, and audit logs stay aligned the moment content ships.
What is WorkOS?
WorkOS is a developer platform for adding enterprise auth to B2B apps, including SSO, Directory Sync, User Management, Organizations, RBAC, Admin Portal, and Audit Logs. Teams use WorkOS when customers ask for SAML, OIDC, SCIM provisioning, and customer-visible audit trails without building every identity protocol from scratch. Its APIs and SDKs are common in SaaS products that sell to companies with strict IT requirements.
Why integrate WorkOS with a headless CMS?
Enterprise auth gets messy when identity setup and content live in separate places. Your sales team may promise SAML for acme.com, your product team may publish tenant-specific onboarding instructions, and your IT admin may expect WorkOS Admin Portal links, Directory Sync copy, and audit log events to match the exact organization they’re configuring. If those fields are copied by hand, one typo in a domain or one stale role label can block a customer’s launch.
Architecture overview
A typical setup starts in Sanity Studio, where an editor publishes an enterpriseOrganization document with fields like name, slug, domains, workosOrganizationId, roleMappings, adminPortalInstructions, and localized onboarding copy. The document is written to the Content Lake as structured JSON. A Sanity webhook or Function listens for publish events with a GROQ filter such as _type == "enterpriseOrganization" && !(_id in path("drafts.**")), then fetches the exact projection WorkOS needs with GROQ. The server-side handler uses the WorkOS Node SDK and a WorkOS API key to call WorkOS APIs, for example creating an audit log event with auditLogs.createEvent, updating organization metadata in your app, or generating Admin Portal links from your back end. Your frontend then reads the same Sanity tenant content and uses the WorkOS organization ID when sending users through AuthKit, SSO, or Admin Portal flows. The end user sees the right login path, organization copy, role labels, and setup instructions without your team copying data between tools.
Common use cases
Enterprise SSO onboarding
Publish tenant-specific SAML or OIDC setup instructions in Sanity and connect them to the matching WorkOS organization ID and verified domains.
Directory Sync role guidance
Structure SCIM and directory mapping copy in Sanity so IT admins see clear role, group, and provisioning instructions alongside WorkOS Directory Sync setup.
Customer-visible audit events
Send content publish events from Sanity to WorkOS Audit Logs so enterprise customers can see when help docs, policy pages, or tenant settings changed.
Tenant-aware auth experiences
Use Sanity content to decide which login copy, legal text, and setup links appear for each WorkOS organization before users enter an SSO flow.
Step-by-step integration
- 1
Set up WorkOS
Create a WorkOS account, copy your API key from the dashboard, configure your redirect URI, and install the SDK with npm install @workos-inc/node. If you’re using SSO, create or connect a WorkOS organization and note its org_ ID.
- 2
Model tenant identity content in Sanity Studio
Create an enterpriseOrganization schema with fields such as name, slug, domains, workosOrganizationId, adminPortalInstructions, ssoEnabled, directorySyncEnabled, and roleMappings. Keep WorkOS IDs as plain string fields so they can be queried and used by server-side code.
- 3
Create a publish trigger
Add a Sanity webhook or Function that fires only for relevant documents. Use a GROQ filter like _type == "enterpriseOrganization" && !(_id in path("drafts.**")) so drafts don’t call WorkOS.
- 4
Fetch Sanity content and call WorkOS
In the webhook handler or Function, use @sanity/client to fetch the published document with GROQ. Then use the WorkOS SDK to create audit log events, connect organization IDs to your app records, or generate Admin Portal links from a trusted server.
- 5
Build the frontend flow
Query Sanity for the tenant page, show the correct SSO or Directory Sync instructions, and send the user into WorkOS AuthKit or an SSO authorization URL using the matched WorkOS organization ID.
- 6
Test with real publish and auth events
Test one tenant with a draft, a publish, an update, and a delete. Confirm Sanity webhooks fire once per expected event, WorkOS receives the right organization ID, and your frontend never exposes the WorkOS API key.
How Sanity + WorkOS works
Build your WorkOS integration on Sanity
Sanity’s AI Content Operating System gives you the structured content foundation, real-time event system, and flexible APIs you need to connect tenant content with WorkOS.
Start building free →CMS approaches to WorkOS
| Capability | Traditional CMS | Sanity |
|---|---|---|
| Tenant and organization modeling | Organization settings often live in pages, plugins, or custom tables, so WorkOS IDs and domain lists can drift from the content editors update. | Schema-as-code lets you model WorkOS organization IDs, domains, role mappings, and setup copy in TypeScript with validation and Git review. |
| Sync on publish | Teams often rely on manual updates, plugin hooks, or scheduled exports, which can delay WorkOS updates. | Webhooks or Functions can run server-side logic on content mutations. Functions include 500,000 invocations per month, but long-running identity workflows should still use a queue. |
| Field-level payload control | Template output or REST endpoints can send more data than WorkOS needs, which increases mapping code. | GROQ fetches exactly the WorkOS payload you need, including joined references such as author email, tenant plan, locale, and role labels. |
| Customer audit logs | Admin logs are usually built for internal editors, not customer-facing audit trails in enterprise SaaS products. | A webhook or Function can map publish events to workos.auditLogs.createEvent with organization, actor, target, and metadata fields. |
| Multi-channel auth content | Auth copy and setup instructions are often tied to one website experience. | One structured back end can feed web, mobile, WorkOS-connected admin flows, and AI agents, with GROQ filters for each tenant and channel. |
Keep building
Explore related integrations to complete your content stack.
Sanity + Auth0
Connect structured tenant content with Auth0 login, organization, and role-based experiences.
Sanity + Clerk
Pair Sanity content models with Clerk user, organization, and session flows for modern SaaS apps.
Sanity + Okta
Use Sanity to publish enterprise onboarding content that matches Okta SSO and identity workflows.