> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-nick-eng-3707-update-chat-endpoints-to-single-assi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/authentication-personalization/overview) to compare options.
Authentication methods are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication).
## 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
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Full Authentication** or **Partial Authentication**.
3. Select **JWT**.
4. Enter the URL of your existing login flow and select **Save changes**.
5. Select **Generate new key**.
6. Store your key securely where it can be accessed by your backend.
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](/authentication-personalization/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}`.
```ts TypeScript
import * as jose from 'jose';
import { Request, Response } from 'express';
const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');
export async function handleRequest(req: Request, res: Response) {
const user = {
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
groups: res.locals.user.groups,
content: {
firstName: res.locals.user.firstName,
lastName: res.locals.user.lastName,
},
};
const jwt = await new jose.SignJWT(user)
.setProtectedHeader({ alg: 'EdDSA' })
.setExpirationTime('10 s') // 10 second JWT expiration
.sign(signingKey);
return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);
}
```
```python Python
import jwt # pyjwt
import os
from datetime import datetime, timedelta
from fastapi.responses import RedirectResponse
private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
@router.get('/auth')
async def return_mintlify_auth_status(current_user):
jwt_token = jwt.encode(
payload={
'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration
'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
'groups': ['admin'] if current_user.is_admin else [],
'content': {
'firstName': current_user.first_name,
'lastName': current_user.last_name,
},
},
key=private_key,
algorithm='EdDSA'
)
return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
```
### 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:
1. User attempts to visit a protected page: `https://docs.foo.com/quickstart`.
2. Redirect to your login URL with a redirect query parameter: `https://foo.com/docs-login?redirect=%2Fquickstart`.
3. After authentication, redirect to `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`.
4. 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
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Full Authentication** or **Partial Authentication**.
3. 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.
4. Select **Save changes**.
1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Add the redirect URL as an authorized redirect URL for your OAuth server.
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](/authentication-personalization/sending-data) for more information.
Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
### 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:
```json
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"groups": ["engineering", "admin"]
}
```
**Configure your OAuth server to allow redirects** to your callback URL.
### Prerequisites
* Your documentation users are also your documentation editors.
### Implementation
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Full Authentication** or **Partial Authentication**.
3. Select **Mintlify Auth**.
4. Select **Enable Mintlify Auth**.
1. In your dashboard, go to [Members](https://dashboard.mintlify.com/settings/organization/members).
2. Add each person who should have access to your documentation.
3. 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
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Full Authentication** or **Partial Authentication**.
3. Select **Password**.
4. Enter a secure password.
5. Select **Save changes**.
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!