You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Enterprise plans](https://mintlify.com/pricing?ref=authentication) include all authentication methods.
12
12
</Info>
13
13
14
-
There are three approaches to manage access and customize your documentation based on user information.
15
14
16
-
-**Authentication**: Complete privacy protection for all content with full content customization.
15
+
Choose from three approaches to manage access and customize your documentation based on user information and your security needs:
16
+
17
+
-**Full authentication**: Complete privacy protection for all content with full content customization.
17
18
-**Partial authentication**: Page-by-page access control with full content customization.
18
19
-**Personalization**: Content customization with **no security guarantees**. All content remains publicly accessible.
19
20
20
-
**Choose authentication** if you need complete security and privacy for all your documentation, including pages, images, search results, and AI assistant features.
21
-
22
-
**Choose partial authentication** if you want some pages to be public and others private.
23
-
24
-
**Choose personalization** if you want to customize content based on user information and your documentation can be publicly accessible.
25
-
26
-
## Handshake methods
27
-
28
-
Authentication and personalization offer multiple handshake methods for controlling access to your content.
29
-
30
-
### Available for all methods
21
+
### Use case examples
31
22
32
-
**JSON Web Token (JWT)**: Custom system where you manage user tokens with full control over the login flow.
23
+
**Choose full authentication when:**
24
+
- Building internal company documentation that contains sensitive information
25
+
- Documenting proprietary APIs that require user verification
- Must be compatible with your existing login flow.
40
-
- Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately.
41
-
- 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.
28
+
**Choose partial authentication when:**
29
+
- Offering public getting-started guides with private advanced features
30
+
- Running a freemium product where premium users get additional documentation
31
+
- Publishing open-source docs with private enterprise sections
42
32
43
-
**OAuth 2.0**: Third-party login integration like Google, GitHub, or other OAuth providers.
33
+
**Choose personalization when:**
34
+
- Creating public API documentation that shows user-specific examples
35
+
- Building marketing sites that customize content based on user profiles
36
+
- Offering public tutorials that adapt to user preferences or skill levels
44
37
45
-
- Pros of OAuth 2.0:
46
-
- Heightened security standard.
47
-
- No restrictions on API URLs.
48
-
- Cons of OAuth 2.0:
49
-
- Requires significant work if setting up an OAuth server for the first time.
50
-
- Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately.
38
+
## Handshake methods
51
39
52
-
### Available for authentication and partial authentication
40
+
Choose the method that best fits your existing infrastructure and security requirements.
53
41
54
-
**Mintlify dashboard**: Allow all of your dashboard users to access your docs.
42
+
| Method | Available for | Setup complexity | Best for |
- Requires all users of your docs to have an account in your Mintlify dashboard.
50
+
### When to use each method
61
51
62
-
**Password**: Shared access with a single global password. Used for access control only. Does not allow for personalization.
52
+
**JWT**: Use when you have an existing authentication system and want full control over the login flow. Ideal for custom user management or when you need to decouple documentation access from your main application.
63
53
64
-
- Pros of password:
65
-
- Simple setup with no configuration required to add new users, just share the password.
66
-
- Cons of password:
67
-
- Lose personalization features since there is no way to differentiate users with the same password.
68
-
- Must change the password to revoke access.
54
+
**OAuth 2.0**: Use when you want to leverage third-party authentication providers (Google, GitHub, etc.) or need enterprise-grade security standards. Best for organizations already using OAuth infrastructure.
69
55
70
-
### Available for personalization
56
+
**Mintlify Dashboard**: Use when your documentation editors are also your documentation readers. Perfect for internal teams who already manage content through the Mintlify dashboard.
71
57
72
-
**Shared session**: Use the same session token as your dashboard to personalize content.
58
+
**Password**: Use for simple access control when you don't need to track individual users or personalize content. Good for contractors, beta users, or temporary access scenarios.
73
59
74
-
- Pros of shared session:
75
-
- Users that are logged into your dashboard are automatically logged into your docs.
76
-
- User sessions are persistent so you can refresh data without requiring a new login.
77
-
- Minimal setup.
78
-
- Cons of shared session:
79
-
- Your docs will make a request to your backend.
80
-
- You must have a dashboard that uses session authentication.
81
-
- CORS configuration is generally required.
60
+
**Shared Session**: Use when you want seamless login between your application and documentation. Ideal when users are already authenticated in your main application and you want to personalize their documentation experience.
82
61
83
62
## Content customization
84
63
85
-
All three methods allow you to customize content with these features.
86
-
87
-
### Dynamic `MDX` content
88
-
89
-
Display dynamic content based on user information like name, plan, or organization.
90
-
91
-
The `user` variable contains information sent to your docs from logged in users. See [Sending data](/authentication-personalization/sending-data) for more information.
92
-
93
-
**Example**: Hello, {user.name??'reader'}!
94
-
95
-
```jsx
96
-
Hello, {user.name??'reader'}!
97
-
```
98
-
99
-
This feature is more powerful when you pair it with custom data about your users. For example, you can give different instructions based on a user's plan.
100
-
101
-
**Example**: Authentication is an enterprise feature. {
102
-
user.org === undefined
103
-
? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
104
-
: user.org.plan !== 'enterprise'
105
-
? <>You are currently on the ${user.org.plan??'free'} plan. See<a href="https://mintlify.com/pricing">our pricing page</a>for information about upgrading.</>
106
-
:<>To request this feature for your enterprise org, contact your admin.</>
107
-
}
108
-
109
-
```jsx
110
-
Authentication is an enterprise feature. {
111
-
user.org === undefined
112
-
? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
113
-
: user.org.plan !== 'enterprise'
114
-
? <>You are currently on the ${user.org.plan??'free'} plan. See<a href="https://mintlify.com/pricing">our pricing page</a>for information about upgrading.</>
115
-
:<>To request this feature for your enterprise org, contact your admin.</>
116
-
}
117
-
```
118
-
119
-
<Note>
120
-
The information in `user` is only available for logged in users. For logged
121
-
out users, the value of `user` will be `{}`. To prevent the page from crashing
122
-
for logged out users, always use optional chaining on your `user` fields. For
123
-
example, `{user.org?.plan}`.
124
-
</Note>
125
-
126
-
### API key prefilling
127
-
128
-
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.
129
-
130
-
### Page visibility
131
-
132
-
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.
133
-
134
-
Users will only see pages for `groups` that they are in.
135
-
136
-
```mdx
137
-
---
138
-
title:"Managing your users"
139
-
description:"Adding and removing users from your organization"
140
-
groups: ["admin"]
141
-
---
142
-
```
64
+
All three approaches support content personalization features including dynamic MDX content, API key prefilling, and page visibility controls. For detailed implementation guidance, see [Personalization setup](/authentication-personalization/personalization-setup).
0 commit comments