Skip to content

add auth keyword to auth pages #841

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.

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 2 commits into from
Jun 23, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions authentication-personalization/authentication-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
title: "Authentication setup"
description: "Guarantee 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.

Expand All @@ -19,7 +20,7 @@
<Tab title="JWT">
### Prerequisites

* An authentication system that can generate and sign JWTs.

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

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L23

Did you really mean 'JWTs'?
* A backend service that can create redirect URLs.

### Implementation
Expand Down Expand Up @@ -54,20 +55,20 @@

<CodeGroup>
```ts TypeScript
import * as jose from 'jose';

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

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L58

Did you really mean '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');

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

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L63

Did you really mean 'signingKey'?

export async function handleRequest(req: Request, res: Response) {
const user = {
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration

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

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L67

Did you really mean 'expiresAt'?
groups: res.locals.user.groups,
content: {
firstName: res.locals.user.firstName,

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

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L70

Did you really mean 'firstName'?
lastName: res.locals.user.lastName,

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

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L71

Did you really mean 'lastName'?
},
};

Expand Down Expand Up @@ -168,8 +169,8 @@
```json
{
"content": {
"firstName": "Jane",

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

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L172

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

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

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/authentication-setup.mdx#L173

Did you really mean 'lastName'?
},
"groups": ["engineering", "admin"]
}
Expand Down
90 changes: 49 additions & 41 deletions authentication-personalization/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,19 @@
title: "Overview"
description: "Control who sees your documentation and customize their experience"
icon: "badge-info"
keywords: ["auth"]
---

<Info>
Authentication methods are available on the [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication).
Authentication methods are available on the [Growth and Enterprise
plans](https://mintlify.com/pricing?ref=authentication).
</Info>

There are three approaches to manage access and customize your documentation based on user information.

* **Authentication**: Complete privacy protection for all content with full content customization.
* **Partial authentication**: Page-by-page access control with full content customization.
* **Personalization**: Content customization with **no security guarantees**. All content remains publicly accessible.
- **Authentication**: Complete privacy protection for all content with full content customization.
- **Partial authentication**: Page-by-page access control with full content customization.
- **Personalization**: Content customization with **no security guarantees**. All content remains publicly accessible.

**Choose authentication** if you need complete security and privacy for all your documentation, including pages, images, search results, and AI assistant features.

Expand All @@ -26,50 +29,55 @@
### Available for all methods

**JSON Web Token (JWT)**: Custom system where you manage user tokens with full control over the login flow.
* Pros of JWT:
* Reduced risk of API endpoint abuse.
* No CORS configuration.
* No restrictions on API URLs.
* Cons of JWT:
* Must be compatible with your existing login flow.
* Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately.
* When you refresh user data, users must log into your docs again. If your users' data changes frequently, they must log in frequently or risk having stale data in your docs.

- Pros of JWT:
- Reduced risk of API endpoint abuse.
- No CORS configuration.
- No restrictions on API URLs.
- Cons of JWT:
- Must be compatible with your existing login flow.
- Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately.
- When you refresh user data, users must log into your docs again. If your users' data changes frequently, they must log in frequently or risk having stale data in your docs.

**OAuth 2.0**: Third-party login integration like Google, GitHub, or other OAuth providers.
* Pros of OAuth 2.0:
* Heightened security standard.
* No restrictions on API URLs.
* Cons of OAuth 2.0:
* Requires significant work if setting up an OAuth server for the first time.
* Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately.

### Available for authentication and partial authentication
- Pros of OAuth 2.0:
- Heightened security standard.
- No restrictions on API URLs.
- Cons of OAuth 2.0:
- Requires significant work if setting up an OAuth server for the first time.
- Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately.

### Available for authentication and partial authentication

**Mintlify dashboard**: Allow all of your dashboard users to access your docs.
* Pros of Mintlify dashboard:
* No configuration required.
* Enables private preview deployments, restricting access to authenticated users only.
* Cons of Mintlify dashboard:
* Requires all users of your docs to have an account in your Mintlify dashboard.

- Pros of Mintlify dashboard:
- No configuration required.
- Enables private preview deployments, restricting access to authenticated users only.
- Cons of Mintlify dashboard:
- Requires all users of your docs to have an account in your Mintlify dashboard.

**Password**: Shared access with a single global password. Used for access control only. Does not allow for personalization.
* Pros of password:
* Simple setup with no configuration required to add new users, just share the password.
* Cons of password:
* Lose personalization features since there is no way to differentiate users with the same password.
* Must change the password to revoke access.

- Pros of password:
- Simple setup with no configuration required to add new users, just share the password.
- Cons of password:
- Lose personalization features since there is no way to differentiate users with the same password.
- Must change the password to revoke access.

### Available for personalization

**Shared session**: Use the same session token as your dashboard to personalize content.
* Pros of shared session:
* Users that are logged into your dashboard are automatically logged into your docs.
* User sessions are persistent so you can refresh data without requiring a new login.
* Minimal setup.
* Cons of shared session:
* Your docs will make a request to your backend.
* You must have a dashboard that uses session authentication.
* CORS configuration is generally required.

- Pros of shared session:
- Users that are logged into your dashboard are automatically logged into your docs.
- User sessions are persistent so you can refresh data without requiring a new login.
- Minimal setup.
- Cons of shared session:
- Your docs will make a request to your backend.
- You must have a dashboard that uses session authentication.
- CORS configuration is generally required.

## Content customization

Expand Down Expand Up @@ -108,19 +116,19 @@
```

<Note>
The information in `user` is only available for logged in users. For
logged out users, the value of `user` will be `{}`. To prevent the page from
crashing for logged out users, always use optional chaining on your `user`
fields. For example, `{user.org?.plan}`.
The information in `user` is only available for logged in users. For logged
out users, the value of `user` will be `{}`. To prevent the page from crashing
for logged out users, always use optional chaining on your `user` fields. For
example, `{user.org?.plan}`.
</Note>

### API key prefilling

Check warning on line 125 in authentication-personalization/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/overview.mdx#L125

Did you really mean 'prefilling'?

Automatically populate API playground fields with user-specific values by returning matching field names in your user data. The field names in your user data must exactly match the names in the API playground for automatic prefilling to work.

Check warning on line 127 in authentication-personalization/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/overview.mdx#L127

Did you really mean 'prefilling'?

### Page visibility

Restrict which pages are visible to your users by adding `groups` fields to your pages' frontmatter. By default, every page is visible to every user.

Check warning on line 131 in authentication-personalization/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/overview.mdx#L131

Did you really mean 'frontmatter'?

Users will only see pages for `groups` that they are in.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
title: "Partial authentication setup"
description: "Control access to specific pages"
icon: "file-lock-2"
keywords: ["auth"]
---

Partial authentication lets you protect private documentation while keeping other pages publicly viewable. Users can browse public content freely and authenticate only when accessing protected pages.
Expand All @@ -14,7 +15,7 @@

## Making pages public

By default, all pages are protected. Add the `public` property to the page's frontmatter to make it viewable without authentication:

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

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

authentication-personalization/partial-authentication-setup.mdx#L18

Did you really mean 'frontmatter'?

```mdx
---
Expand Down