Skip to content

Consolidate auth docs #999

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Aug 7, 2025
Merged

Consolidate auth docs #999

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
940e3e6
hide overview
ethanpalm Aug 6, 2025
8acdd6b
reorder auth methods
ethanpalm Aug 6, 2025
311bc2a
combine partial and full auth
ethanpalm Aug 6, 2025
2196da8
format JSON example
ethanpalm Aug 6, 2025
bf78486
move Sending data into Personalization
ethanpalm Aug 6, 2025
6af6398
set up redirects
ethanpalm Aug 6, 2025
ba47263
add more conceptual info to personalization
ethanpalm Aug 6, 2025
a6d7946
move longer example to later in page
ethanpalm Aug 6, 2025
706a2b4
update all ParamFields
ethanpalm Aug 6, 2025
255e934
copyedit
ethanpalm Aug 6, 2025
136ef78
copyedit overview
ethanpalm Aug 6, 2025
e986a47
appease the broken link checker
ethanpalm Aug 6, 2025
2ca2592
add OIDC
ethanpalm Aug 7, 2025
bba9997
add logout URL
ethanpalm Aug 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
283 changes: 170 additions & 113 deletions authentication-personalization/authentication-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,153 @@
---
title: "Authentication setup"
description: "Guarantee privacy of your docs by authenticating users"
description: "Control the privacy of your docs by authenticating users"
icon: "file-lock"
keywords: ['auth']
---
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.

<Info>
[Pro plans](https://mintlify.com/pricing?ref=authentication) include password authentication.

[Enterprise plans](https://mintlify.com/pricing?ref=authentication) include all authentication methods.
</Info>

Authentication requires users to log in before accessing your documentation.

## Authentication modes

Choose between full and partial authentication modes based on your access control needs.

**Full authentication**: All pages are protected. Users must log in before accessing any content.

**Partial authentication**: Some pages are publicly viewable while others require authentication. Users can browse public content freely and authenticate only when accessing protected pages.

When configuring any handshake method below, you'll select either **Full authentication** or **Partial authentication** in your dashboard settings.

## Configuring authentication

Select the handshake method that you want to configure.

<Tabs>
<Tab title="Password">
<Info>
Password authentication provides access control only and does **not** support content personalization.
</Info>

### Prerequisites

* Your security requirements allow sharing passwords among users.

### Implementation

<Steps>
<Step title="Create a password.">
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**.
</Step>
<Step title="Distribute access.">
Securely share the password and documentation URL with authorized users.
</Step>
</Steps>

## 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!
</Tab>
<Tab title="Mintlify Dashboard">
### Prerequisites

* Your documentation users are also your documentation editors.

### Implementation

<Steps>
<Step title="Enable Mintlify dashboard authentication.">
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**.
</Step>
<Step title="Add authorized users.">
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.
</Step>
</Steps>

### 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.
</Tab>
<Tab title="OAuth 2.0">
### Prerequisites

* An OAuth or OIDC server that supports the Authorization Code Flow.
* Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable personalization features).

### Implementation

<Steps>
<Step title="Configure your OAuth settings.">
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.
* **Logout URL**: The native logout URL for your OAuth provider. If your provider has a `returnTo` or similar parameter, point it back to your docs URL.
4. Select **Save changes**.
</Step>
<Step title="Configure your OAuth server.">
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.
</Step>
<Step title="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](/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).
</Step>
</Steps>

### 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`
- **Logout URL**: `https://auth.foo.com/logout?returnTo=https%3A%2F%2Ffoo.com%2Fdocs`

**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",

Check warning on line 142 in authentication-personalization/authentication-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L142 

Did you really mean 'firstName'?
"lastName": "Doe"

Check warning on line 143 in authentication-personalization/authentication-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L143 

Did you really mean 'lastName'?
},
"groups": ["engineering", "admin"]
}
```

**Configure your OAuth server to allow redirects** to your callback URL.
</Tab>
<Tab title="JWT">
### Prerequisites

Expand Down Expand Up @@ -121,122 +250,50 @@
3. After authentication, redirect to `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`.
4. User lands in their original destination.
</Tab>
<Tab title="OAuth 2.0">
### Prerequisites
</Tabs>

* 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).
## Making pages public

### Implementation
When using partial authentication, all pages are protected by default. You can make specific pages viewable without authentication at the page or group level with the `public` property.

<Steps>
<Step title="Configure your OAuth settings.">
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**.
</Step>
<Step title="Configure your OAuth server.">
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.
</Step>
<Step title="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](/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).
</Step>
</Steps>
### Page level

### Example
To make a page public, add `public: true` to the page's frontmatter.

Check warning on line 261 in authentication-personalization/authentication-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L261 

Did you really mean 'frontmatter'?

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.
```mdx Public page example
---
title: "Public page"
public: true
---
```

**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`
### Group level

**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:
To make all pages in a group public, add `"public": true` beneath the group's name in the `navigation` object of your `docs.json`.

```json
```json Public group example
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"groups": ["engineering", "admin"]
"navigation": {
"groups": [
{
"group": "Public group",
"public": true,
"icon": "play",
"pages": [
"quickstart",
"installation",
"settings"
]
},
{
"group": "Private group",
"icon": "pause",
"pages": [
"private-information",
"secret-settings"
]
}
]
}
}
```

**Configure your OAuth server to allow redirects** to your callback URL.
</Tab>
<Tab title="Mintlify Dashboard">
### Prerequisites

* Your documentation users are also your documentation editors.

### Implementation

<Steps>
<Step title="Enable Mintlify dashboard authentication.">
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**.
</Step>
<Step title="Add authorized users.">
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.
</Step>
</Steps>

### 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.
</Tab>
<Tab title="Password">
<Info>
Password authentication provides access control only and does **not** support content personalization.
</Info>

### Prerequisites

* Your security requirements allow sharing passwords among users.

### Implementation

<Steps>
<Step title="Create a password.">
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**.
</Step>
<Step title="Distribute access.">
Securely share the password and documentation URL with authorized users.
</Step>
</Steps>

## 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!
</Tab>
</Tabs>
```
Loading