Authentication

Overview

If you use a managed authentication service, such as Auth0, Clerk, or OpenID, you can implement this into your site and allow users to browse and interact with your documentation and API reference in a logged in state.

Configuration

To implement the authentication option for your site, add the authentication property to the Zudoku Configuration file. The configuration is slightly different depending on the authentication provider you use.

Authentication Providers

Zudoku supports Clerk, Auth0, Supabase, Firebase, Microsoft Entra ID, Azure B2C, and any OpenID Connect provider (including Okta, Keycloak, Authentik, and PingFederate).

Not seeing your authentication provider? Let us know

Auth0

For Auth0, you will need the clientId associated with the domain you are using.

You can find this in the Auth0 dashboard under Application Settings.

Code
{
  // ...
  authentication: {
    type: "auth0",
    domain: "yourdomain.us.auth0.com",
    clientId: "<your-auth0-clientId>",
    scopes: ["openid", "profile", "email", "custom_scope"],
  },
  // ...
}

To setup Auth0, create a Single Page Application (SPA) application in the Auth0 dashboard. Set the following options:

Callback URL to https://your-site.com/oauth/callback.
For development environments only, we recommend configuring your app to allow the a wildcard callback like https://*.zuplo.app/oauth/callback to allow for testing each environment.
For local development, set the callback url to http://localhost:3000/oauth/callback.
Add your site hostname (your-site.com) to the list of allowed CORS origins.

Clerk

For Clerk you will need the publishable key for your application. You can find this in the Clerk dashboard on the API Keys page.

Code
{
  // ...
  authentication: {
    type: "clerk",
    clerkPubKey: "<your-clerk-publishable-key>",
    // Optional. See: https://clerk.com/docs/backend-requests/jwt-templates
    jwtTemplateName: "dev-portal",
  },
  // ...
}

OpenID

For authentication services that support OpenID, you will need to supply an clientId and issuer.

Code
{
  // ...
  authentication: {
    type: "openid",
    clientId: "<your-client-id>",
    issuer: "<the-issuer-url>",
    scopes: ["openid", "profile", "email", "custom_scope"] // Optional custom scopes
  },
  // ...
}

When configuring your OpenID provider, you will need to set the following:

Callback or Redirect URI to https://your-site.com/oauth/callback.
If your provider supports wildcard callback urls, we recommend configuring your development identity provider to allow a wildcard callback like https://*.zuplo.site/oauth/callback to allow for testing each environment.
For local development set the callback url to http://localhost:3000/oauth/callback.
Add your site hostname (your-site.com) to the list of allowed CORS origins.

By default, the scopes "openid", "profile", and "email" are requested. You can customize these by providing your own array of scopes.

For provider-specific guides (Okta, Keycloak, etc.), see the OpenID Connect setup page.

Microsoft Entra ID

For Microsoft Entra ID (formerly Azure AD), you will need the clientId from your app registration and your tenantId.

Code
{
  // ...
  authentication: {
    type: "entra",
    clientId: "<your-application-client-id>",
    tenantId: "<your-tenant-id>", // Or "common" for multitenant. Defaults to "common".
  },
  // ...
}

For full setup instructions, see the Azure AD / Entra ID setup guide.

Firebase

For Firebase authentication, you will need your Firebase project configuration. You can find this in the Firebase console under Project Settings.

Code
{
  // ...
  authentication: {
    type: "firebase",
    apiKey: "<your-firebase-api-key>",
    authDomain: "<your-project>.firebaseapp.com",
    projectId: "<your-project-id>",
    appId: "<your-app-id>",
    providers: ["google", "github", "password"], // Optional
  },
  // ...
}

The providers option configures which sign-in methods are available. Supported providers include: google, facebook, twitter, github, microsoft, apple, yahoo, password, and emailLink.

For detailed setup instructions, see the Firebase setup guide.

Supabase

To use Supabase as your authentication provider, supply your project's URL, API key, and the OAuth providers to use.

Code
{
  // ...
  authentication: {
    type: "supabase",
    providers: ["github"],
    supabaseUrl: "https://your-project.supabase.co",
    supabaseKey: "<your-supabase-key>",
    redirectToAfterSignUp: "/",
    redirectToAfterSignIn: "/",
    redirectToAfterSignOut: "/",
  },
  // ...
}

The providers option accepts an array of Supabase Auth's supported providers, such as apple, azure, bitbucket, discord, facebook, figma, github, gitlab, google, kakao, keycloak, linkedin, linkedin_oidc, notion, slack, slack_oidc, spotify, twitch, twitter, workos, zoom, or fly.

Azure B2C

For Azure B2C authentication, you will need to provide your Azure B2C tenant name, client ID, and policy name.

Code
{
  // ...
  authentication: {
    type: "azureb2c",
    clientId: "<your-azure-b2c-client-id>",
    tenantName: "<your-tenant-name>",
    policyName: "<your-policy-name>",
    issuer: "<your-issuer-url>",
    scopes: ["openid", "profile", "email", "custom_scope"]
  },
  // ...
}

When configuring your Azure B2C application, you will need to set the following:

Redirect URI to https://your-site.com/oauth/callback
For local development, set the redirect URI to http://localhost:3000/oauth/callback
Add your site hostname (your-site.com) to the list of allowed CORS origins
Configure the appropriate user flows (policies) in your Azure B2C tenant

By default, the scopes "openid", "profile", and "email" are requested. You can customize these by providing your own array of scopes.

User Data

After the user authenticates, the user profile is loaded via the provider's User Info endpoint. The following fields are used to display the user profile:

name - The user's full name
email - The user's email address
picture - The user's profile picture URL
email_verified - Whether the user's email address has been verified

If the provider does not return a field, it will be left blank.

By default, users return to the page they started from after signing in. For protected routes that is the path and query string they tried to open; for useAuth().login({ redirectTo }) it is the redirectTo you pass.

Setting redirectToAfterSignIn overrides that return URL: every sign-in lands on the configured path instead. Only set it if you always want users to land on the same page, and leave it unset to return users to where they were. redirectToAfterSignUp behaves the same way for sign-up.

Code
{
  authentication: {
    type: "auth0",
    // ...
    // Omit to return users to the page they came from
    redirectToAfterSignIn: "/docs",
  },
}

This applies to all built-in providers. For Supabase social (OAuth) sign-in, the return URL must also be allowed under Redirect URLs in your Supabase project's authentication settings, and a return URL on another origin falls back to your site's root.

Protected Routes

Once authentication is configured, you can protect specific routes in your documentation to require users to be authenticated or meet custom authorization requirements. Routes can be protected with a simple array of patterns, or with custom callback functions that support reason codes for distinguishing between unauthorized and forbidden access.

Code
{
  // ...
  // Simple array format: requires authentication
  protectedRoutes: [
    "/admin/*",
    "/settings",
    "/api/*",
  ],

  // Or object format: custom authorization with reason codes
  protectedRoutes: {
    "/admin/*": ({ auth, reasonCode }) =>
      !auth.isAuthenticated
        ? reasonCode.UNAUTHORIZED
        : auth.profile?.email?.endsWith("@example.com")
          ? true
          : reasonCode.FORBIDDEN,
  },
  // ...
}

See the Protected Routes documentation for detailed information on configuring route protection, reason codes, and navigation behavior.

Edit this page

Last modified on September 24, 2026

x-zudoku-type OAuth Security Schemes