How to Integrate FusionAuth with Your Headless CMS

What is FusionAuth?

FusionAuth is a customer identity and access management platform for login, registration, OAuth2, OpenID Connect, SAML, MFA, passwordless auth, and user lifecycle APIs. Teams use it when they need cloud or self-hosted identity infrastructure with tenant, application, role, group, and user data controls.

Why integrate FusionAuth with a headless CMS?

Auth data and content rules often live in different places. Your product team defines a paid learning path, a partner-only resource center, or a region-specific onboarding flow in the headless CMS, while your engineering team maintains roles, groups, and user metadata in FusionAuth. If those systems don't talk to each other, someone ends up copying slugs, role names, application IDs, or access rules by hand.

A headless CMS integration gives you one publish event that can update identity data automatically. With Sanity, access policies, gated content metadata, onboarding copy, and profile fields are structured as typed JSON in the Content Lake. A GROQ query can select only the fields FusionAuth needs, such as requiredRoles, fusionAuthApplicationId, tenantId, and linked user IDs. Webhooks or Functions can then call FusionAuth APIs as soon as a document is published, updated, or deleted.

The trade-off is that you need to be clear about ownership. FusionAuth should remain the source for authentication, credentials, sessions, MFA, and tokens. Sanity should model the content and business rules that editors need to change. When that boundary is clear, you avoid nightly CSV jobs, stale entitlement tables, and production deploys just to change who can see a resource.

Architecture overview

A typical flow starts in Sanity Studio, where an editor publishes an accessPolicy, gatedPage, course, or memberProfile document. The document includes fields FusionAuth can act on, such as fusionAuthUserId, fusionAuthApplicationId, requiredRoles, tenantId, region, or plan. A Sanity webhook fires on the publish event. You can send a small payload, for example the document _id and _type, instead of sending the full document. A webhook listener or Sanity Function receives that event, verifies the secret, and fetches the current document from the Content Lake with GROQ. The query can join referenced documents, so the sync logic gets exactly what it needs in one request. From there, the server-side code calls FusionAuth. Common calls include PATCH /api/user/{userId} to update user.data, POST /api/user/registration/{userId} to register a user for an application, PATCH /api/user/registration/{userId}/{applicationId} to update registration.data or roles, and role or group APIs when your content model controls application access. The end user signs in through FusionAuth hosted login or your own OpenID Connect flow, receives tokens with the right claims, and your app uses those claims when deciding which Sanity-powered content to show.

Common use cases

Step-by-step integration

1. 1

   Set up FusionAuth

   Create a FusionAuth tenant and application, configure redirect URLs for your frontend, and create an API key with only the permissions your sync needs, such as user read, user patch, registration read, and registration patch.

2. 2

   Install the SDKs

   In your webhook handler, Function, or middleware package, install the FusionAuth TypeScript client and Sanity client with npm install @fusionauth/typescript-client @sanity/client.

3. 3

   Model identity-linked content in Sanity Studio

   Add fields such as fusionAuthUserId, fusionAuthApplicationId, requiredRoles, tenantId, plan, locale, and protectedSlug. Keep credentials, passwords, and MFA settings out of Sanity. Those belong in FusionAuth.

4. 4

   Create the sync trigger

   Use a Sanity webhook filtered to the document types you care about, such as _type == 'accessPolicy' or _type == 'memberProfile'. For server-side logic without separate infrastructure, put the handler in a Sanity Function.

5. 5

   Call FusionAuth from server-side code

   Fetch the published Sanity document with GROQ, map the fields to FusionAuth user.data, registration.data, roles, or groups, and call the FusionAuth API. Make the sync idempotent so repeat webhook deliveries don't create duplicate state.

6. 6

   Test the frontend experience

   Sign in through FusionAuth, inspect the ID token or access token claims, and verify that your app shows the correct Sanity-powered content for at least three cases: allowed user, denied user, and recently changed access rule.

How Sanity + FusionAuth works

CMS approaches to FusionAuth

Keep building

Explore related integrations to complete your content stack.