# Configure OAuth 2.0 authentication with Auth0 (/help-center/configure-oauth-with-auth0)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1153 · updated: 2026-09-23 -->

Auth0 is an OAuth 2.0 and OIDC-compliant identity provider, so it plugs directly into Mintlify's built-in OAuth 2.0 support. This page maps Auth0's endpoints and settings onto the fields in [Authentication setup](/deploy/authentication-setup#oauth-2-0). Use the canonical setup page for the full flow and refer here for the Auth0-specific values.

OAuth 2.0 authentication is available on the Enterprise plan.

<Note>
  **Security disclaimer**: While we provide this guide to help you integrate Auth0 with Mintlify, consult with your security team before implementing any authentication solution. Mintlify is not responsible for any security issues that may arise from your specific implementation.
</Note>

## Prerequisites [#prerequisites]

* An Auth0 tenant. Note your tenant domain, for example `your-tenant.us.auth0.com`.
* An Auth0 **Regular Web Application** created for your documentation site. To create one, go to **Applications** > **Applications** in your Auth0 dashboard, click **Create Application**, and select **Regular Web Applications** as the application type.
* The client ID and client secret for that application, found on the application settings page.

## Map Auth0 to Mintlify's OAuth fields [#map-auth0-to-mintlifys-oauth-fields]

In your Mintlify dashboard, go to [Authentication](https://app.mintlify.com/products/authentication), set site visibility to **Private**, and select **Custom** → **OAuth**. Fill in the fields with the following Auth0 values. Replace `YOUR_AUTH0_DOMAIN` with your tenant domain.

| Mintlify field          | Auth0 value                                                             |
| ----------------------- | ----------------------------------------------------------------------- |
| Authorization URL       | `https://YOUR_AUTH0_DOMAIN/authorize`                                   |
| Token URL               | `https://YOUR_AUTH0_DOMAIN/oauth/token`                                 |
| Client ID               | Application client ID from Auth0                                        |
| Client Secret           | Application client secret from Auth0                                    |
| Scopes                  | `openid profile email` (add more if your app needs them)                |
| Info API URL (optional) | `https://YOUR_AUTH0_DOMAIN/userinfo`                                    |
| Logout URL (optional)   | `https://YOUR_AUTH0_DOMAIN/v2/logout?returnTo=<url-encoded-return-url>` |

Save the settings. Mintlify redeploys your site with the new authentication configuration.

## Register the redirect URL in Auth0 [#register-the-redirect-url-in-auth0]

Copy the **Redirect URL** shown in your Mintlify authentication settings and add it to your Auth0 application under **Application URIs → Allowed Callback URLs**. Save the Auth0 application. Without this step, Auth0 rejects the login flow.

If you set a **Logout URL** in Mintlify, add the same return URL to your Auth0 application's **Allowed Logout URLs**.

## Group-based access control [#group-based-access-control]

To restrict pages to specific Auth0 users, you have two options.

* **Token claims (recommended).** Add a groups claim to the ID token or access token with an [Auth0 Action](https://auth0.com/docs/customize/actions) and configure Mintlify to read it. See [Use groups from OAuth token claims](/deploy/authentication-setup#use-groups-from-oauth-token-claims). If you source groups from the ID token, keep `openid` in your scopes.
* **Info API URL.** Point Mintlify at `https://YOUR_AUTH0_DOMAIN/userinfo` or your own endpoint that returns user data in the [User data format](/deploy/authentication-setup#user-data-format). The endpoint must accept `Authorization: Bearer <access_token>` and return groups in the response.

Then add a matching `groups` value to the frontmatter of each page you want to restrict so only members of that group can see it.

## Troubleshooting [#troubleshooting]

* **Callback URL mismatch.** Auth0 blocks the login and shows a callback error. Confirm the redirect URL in Auth0's **Allowed Callback URLs** exactly matches the one shown in your Mintlify authentication settings, including protocol and trailing path.
* **Users log in but see no restricted content.** Your groups claim is not reaching Mintlify. Confirm the Auth0 Action adds the claim, that `source` in Mintlify matches the token you set it on (`id_token` or `access_token`), and that `groupsClaim` matches the claim name.
* **Logout does not redirect back.** Auth0 requires the `returnTo` URL in the logout link to be listed under **Allowed Logout URLs** on the application.