Introduction
Give your users a personalized docs experience
Sometimes, when writing docs, you wish you knew just a little bit about the person reading them. Maybe you only want to show them the information they should care about. Maybe you want to craft examples that they can use out-of-the-box.
With Mintlify, you can add User Auth to identify your users and tailor your docs content to them.
What is User Auth
User Auth allows you to configure a method for identifying and authenticating your users. Once authenticated, you can share user-specific information that can be used to personalize the docs. This unlocks some powerful features:
- Customize MDX content with a user’s information, such as their name, plan, or title.
- Prefill API keys in the API Playground for streamlined use.
- Selectively show pages in the navigation based on a user’s groups.
What isn’t User Auth
At this time, User Auth cannot provide any of the following:
- Private docs content. While you can hide pages from unauthenticated users, those pages are still accessible by anyone who can guess the URL. If your documentation contains sensitive information, User Auth is not enough to hide it.
- A Mintlify-backed user database. Mintlify does not store any information about your users. Rather, it relies on your existing infrastructure to serve as the source-of-truth for user data.
How to Use
Customizing MDX Content
When writing content, you can use the userContext variable to access the information you have sent to your docs. Here’s a simple example:
Hello, !
Hello, {userContext.name ?? 'reader'}!
This feature becomes even more powerful when paired with custom data about the user. Here’s a real world example that allows us to give specific instructions on how to access the User Auth feature based on the customer’s existing plan:
User Auth is an enterprise feature.
User Auth is an enterprise feature. {
userContext.org === undefined
? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
: userContext.org.plan !== 'enterprise'
? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</>
: <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
}
The information in userContext is only available after a user has logged in. For logged out users, the value of userContext will be {}. To prevent the page from crashing for logged-out users, always use optional chaining on your userContext fields, e.g. {userContext.org?.plan}
Prefilling API Keys
If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground.
Showing/Hiding Pages
By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a groups field in your page metadata.
When determining which pages to show to the user, Mintlify will check which groups the user belongs to.
If the user is not in any of the groups listed in the page metadata, the page will not be shown.
---
title: 'Managing Your Users'
description: 'Adding and removing users from your organization'
groups: ['admin']
---
Here’s a table that displays whether a page is shown for different combinations of groups in UserInfo and page metadata:
groups not in UserInfo | groups: [] in UserInfo | groups: ['admin'] in UserInfo | |
|---|---|---|---|
groups not in metadata | ✅ | ✅ | ✅ |
groups: [] in metadata | ❌ | ❌ | ❌ |
groups: ['admin'] in metadata | ❌ | ❌ | ✅ |
Was this page helpful?