Authentication Setup
Guarantee privacy of your docs by authenticating users
Authentication requires users to log in before accessing your documentation. This guide covers setup for each available handshake method.
Need help choosing? See the overview to compare options.
Authentication methods are available on the Growth and Enterprise plans. Please contact sales for more information.
Configuring authentication
Select the handshake method that you want to configure.
Prerequisites
- An authentication system that can generate and sign JWTs.
- A backend service that can create redirect URLs.
Implementation
Generate a private key.
- In your dashboard, go to Authentication.
- Select Full Authentication or Partial Authentication.
- Select JWT.
- Enter the URL of your existing login flow and select Save changes.
- Select Generate new key.
- Store your key securely where it can be accessed by your backend.
Integrate Mintlify authentication into your login flow.
Modify your existing login flow to include these steps after user authentication:
- Create a JWT containing the authenticated user’s info in the
User
format. See Sending Data for more information. - Sign the JWT with your secret key, using the EdDSA algorithm.
- Create a redirect URL back to the
/login/jwt-callback
path of your docs, including the JWT as the hash.
Example
Your documentation is hosted at docs.foo.com
with an existing authentication system at foo.com
. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don’t have a dashboard).
Create a login endpoint at https://foo.com/docs-login
that extends your existing authentication.
After verifying user credentials:
- Generate a JWT with user data in Mintlify’s format.
- Sign the JWT and redirect to
https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}
.
Redirecting unauthenticated users
When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL:
- User attempts to visit a protected page:
https://docs.foo.com/quickstart
. - Redirect to your login URL with a redirect query parameter:
https://foo.com/docs-login?redirect=%2Fquickstart
. - After authentication, redirect to
https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}
. - User lands in their original destination.
Prerequisites
- An authentication system that can generate and sign JWTs.
- A backend service that can create redirect URLs.
Implementation
Generate a private key.
- In your dashboard, go to Authentication.
- Select Full Authentication or Partial Authentication.
- Select JWT.
- Enter the URL of your existing login flow and select Save changes.
- Select Generate new key.
- Store your key securely where it can be accessed by your backend.
Integrate Mintlify authentication into your login flow.
Modify your existing login flow to include these steps after user authentication:
- Create a JWT containing the authenticated user’s info in the
User
format. See Sending Data for more information. - Sign the JWT with your secret key, using the EdDSA algorithm.
- Create a redirect URL back to the
/login/jwt-callback
path of your docs, including the JWT as the hash.
Example
Your documentation is hosted at docs.foo.com
with an existing authentication system at foo.com
. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don’t have a dashboard).
Create a login endpoint at https://foo.com/docs-login
that extends your existing authentication.
After verifying user credentials:
- Generate a JWT with user data in Mintlify’s format.
- Sign the JWT and redirect to
https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}
.
Redirecting unauthenticated users
When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL:
- User attempts to visit a protected page:
https://docs.foo.com/quickstart
. - Redirect to your login URL with a redirect query parameter:
https://foo.com/docs-login?redirect=%2Fquickstart
. - After authentication, redirect to
https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}
. - User lands in their original destination.
Prerequisites
- An OAuth server that supports the Authorization Code Flow.
- Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable personalization features).
Implementation
Configure your OAuth settings.
- In your dashboard, go to Authentication.
- Select Full Authentication or Partial Authentication.
- Select OAuth and configure these fields:
- Authorization URL: Your OAuth endpoint.
- Client ID: Your OAuth 2.0 client identifier.
- Client Secret: Your OAuth 2.0 client secret.
- Scopes: Permissions to request. Use multiple scopes if you need different access levels.
- Token URL: Your OAuth token exchange endpoint.
- Info API URL (optional): Endpoint to retrieve user info for personalization. If omitted, the OAuth flow will only be used to verify identity and the user info will be empty.
- Select Save changes.
Configure your OAuth server.
- Copy the Redirect URL from your authentication settings.
- Add the redirect URL as an authorized redirect URL for your OAuth server.
Create your user info endpoint (optional).
To enable personalization features, create an API endpoint that:
- Accepts OAuth access tokens for authentication.
- Returns user data in the
User
format. See Sending Data for more information.
Add this endpoint URL to the Info API URL field in your authentication settings.
Example
Your documentation is hosted at foo.com/docs
and you have an existing OAuth server at auth.foo.com
that supports the Authorization Code Flow.
Configure your OAuth server details in your dashboard:
- Authorization URL:
https://auth.foo.com/authorization
- Client ID:
ydybo4SD8PR73vzWWd6S0ObH
- Scopes:
['docs-user-info']
- Token URL:
https://auth.foo.com/exchange
- Info API URL:
https://api.foo.com/docs/user-info
Create a user info endpoint at api.foo.com/docs/user-info
, which requires an OAuth access token with the docs-user-info
scope, and returns:
Configure your OAuth server to allow redirects to your callback URL.
Prerequisites
- Your documentation users are also your documentation editors.
Implementation
Enable Mintlify dashboard authentication.
- In your dashboard, go to Authentication.
- Select Full Authentication or Partial Authentication.
- Select Mintlify Auth.
- Select Enable Mintlify Auth.
Add authorized users.
- In your dashboard, go to Members.
- Add each person who should have access to your documentation.
- Assign appropriate roles based on their editing permissions.
Example
Your documentation is hosted at docs.foo.com
and your team uses the dashboard to edit your docs. You want to restrict access to team members only.
Enable Mintlify authentication in your dashboard settings.
Verify team access by checking that all team members are added to your organization.
Password authentication provides access control only and does not support content personalization.
Prerequisites
- Your security requirements allow sharing passwords among users.
Implementation
Create a password.
- In your dashboard, go to Authentication.
- Select Full Authentication or Partial Authentication.
- Select Password.
- Enter a secure password.
- Select Save changes.
Distribute access.
Securely share the password and documentation URL with authorized users.
Example
Your documentation is hosted at docs.foo.com
and you need basic access control without tracking individual users. You want to prevent public access while keeping setup simple.
Create a strong password in your dashboard. Share credentials with authorized users. That’s it!