Configure OAuth 2.0 authentication with Auth0

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

​

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.
• The client ID and client secret for that application.

​

Map Auth0 to Mintlify’s OAuth fields

In your Mintlify dashboard, go to Authentication, set site visibility to Private, and choose Custom → OAuth. Fill in the fields with the following Auth0 values. Replace YOUR_AUTH0_DOMAIN with your tenant domain. Save the settings. Mintlify redeploys your site with the new authentication configuration.

​

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

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 and configure Mintlify to read it. See 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. The endpoint must accept Authorization: Bearer <access_token> and return groups in the response.

Then tag pages or navigation groups with a matching groups value so only members of that group can see them.

​

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.