Personalization Setup
Let users log in for customized documentation experiences
Personalization lets you customize your documentation based on user information. This guide covers setup for each available handshake method.
Need help choosing? See the overview to compare options.
Configuring personalization
Select the handshake method that you want to configure.
Prerequisites
- A login system that can generate and sign JWTs.
- A backend service that can create redirect URLs.
Implementation
Generate a private key.
- In your dashboard, go to Authentication.
- Select Personalization.
- Select JWT.
- Enter the URL of your existing login flow and select Save changes.
- Select Generate new key.
- Store your key securely where it can be accessed by your backend.
Integrate Mintlify personalization into your login flow.
Modify your existing login flow to include these steps after user login:
- Create a JWT containing the logged in user’s info in the
User
format. See Sending Data for more information. - Sign the JWT with the secret key, using the ES256 algorithm.
- Create a redirect URL back to your docs, including the JWT as the hash.
Example
Your documentation is hosted at docs.foo.com
. You want your docs to be separate from your dashboard (or you don’t have a dashboard) and enable personalization.
Generate a JWT secret. Then create a login endpoint at https://foo.com/docs-login
that initiates a login flow to your documentation.
After verifying user credentials:
- Generate a JWT with user data in Mintlify’s format.
- Sign the JWT and redirect to
https://docs.foo.com#{SIGNED_JWT}
.
Preserving page anchors
To redirect users to specific sections after login, use this URL format: https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}
.
Example:
- Original URL:
https://docs.foo.com/quickstart#step-one
- Redirect URL:
https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one
Prerequisites
- A login system that can generate and sign JWTs.
- A backend service that can create redirect URLs.
Implementation
Generate a private key.
- In your dashboard, go to Authentication.
- Select Personalization.
- Select JWT.
- Enter the URL of your existing login flow and select Save changes.
- Select Generate new key.
- Store your key securely where it can be accessed by your backend.
Integrate Mintlify personalization into your login flow.
Modify your existing login flow to include these steps after user login:
- Create a JWT containing the logged in user’s info in the
User
format. See Sending Data for more information. - Sign the JWT with the secret key, using the ES256 algorithm.
- Create a redirect URL back to your docs, including the JWT as the hash.
Example
Your documentation is hosted at docs.foo.com
. You want your docs to be separate from your dashboard (or you don’t have a dashboard) and enable personalization.
Generate a JWT secret. Then create a login endpoint at https://foo.com/docs-login
that initiates a login flow to your documentation.
After verifying user credentials:
- Generate a JWT with user data in Mintlify’s format.
- Sign the JWT and redirect to
https://docs.foo.com#{SIGNED_JWT}
.
Preserving page anchors
To redirect users to specific sections after login, use this URL format: https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}
.
Example:
- Original URL:
https://docs.foo.com/quickstart#step-one
- Redirect URL:
https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one
Prerequisites
- An OAuth server that supports the Auth Code with PKCE Flow.
- Ability to create an API endpoint accessible by OAuth access tokens.
Implementation
Create user info API endpoint.
Create an API endpoint that:
- Accepts OAuth access tokens for authentication.
- Returns user data in the
User
format. See Sending Data for more information. - Defines the scopes for access.
Configure your OAuth personalization settings.
- In your dashboard, go to Authentication.
- Select Personalization.
- Select OAuth and configure these fields:
- Authorization URL: Your OAuth authorization endpoint.
- Client ID: Your OAuth 2.0 client identifier.
- Scopes: Permissions to request. Must match the scopes of the endpoint that you configured in the first step.
- Token URL: Your OAuth token exchange endpoint.
- Info API URL: Endpoint to retrieve user data for personalization. Created in the first step.
- Select Save changes
Configure your OAuth server.
- Copy the Redirect URL from your authentication settings.
- Add this URL as an authorized redirect URL in your OAuth server configuration.
Example
Your documentation is hosted at foo.com/docs
and you have an existing OAuth server that supports the PKCE flow. You want to personalize your docs based on user data.
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 responds with the user’s custom data:
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
Configure your OAuth server to allow redirects to your callback URL.
Prerequisites
- A dashboard or user portal with cookie-based session authentication.
- Ability to create an API endpoint at the same origin or subdomain as your dashboard.
- If your dashboard is at
foo.com
, the API URL must start withfoo.com
or*.foo.com
. - If your dashboard is at
dash.foo.com
, the API URL must start withdash.foo.com
or*.dash.foo.com
.
- If your dashboard is at
- Your docs are hosted at the same domain or subdomain as your dashboard.
- If your dashboard is at
foo.com
, your docs must be hosted atfoo.com
or*.foo.com
. - If your dashboard is at
*.foo.com
, your docs must be hosted atfoo.com
or*.foo.com
.
- If your dashboard is at
Implementation
Create user info API endpoint.
Create an API endpoint that:
- Uses your existing session authentication to identify users
- Returns user data in the
User
format (see Sending Data) - If the API domain and the docs domain do not exactly match:
- Add the docs domain to your API’s
Access-Control-Allow-Origin
header (must not be*
). - Set your API’s
Access-Control-Allow-Credentials
header totrue
.
Only enable CORS headers on this specific endpoint, not your entire dashboard API.
- Add the docs domain to your API’s
Configure your personalization settings
- In your dashboard, go to Authentication.
- Select Personalization.
- Select Shared Session.
- Enter your Info API URL, which is the endpoint from the first step.
- Enter your Login URL, where users log into your dashboard.
- Select Save changes.
Examples
Dashboard at subdomain, docs at subdomain
You have a dashboard at dash.foo.com
, which uses cookie-based session authentication. Your dashboard API routes are hosted at dash.foo.com/api
. You want to set up personalization for your docs hosted at docs.foo.com
.
Setup process:
- Create endpoint
dash.foo.com/api/docs/user-info
that identifies users via session authentication and responds with their user data. - Add CORS headers for this route only:
Access-Control-Allow-Origin
:https://docs.foo.com
Access-Control-Allow-Credentials
:true
- Configure API URL in authentication settings:
https://dash.foo.com/api/docs/user-info
.
Dashboard at subdomain, docs at root
You have a dashboard at dash.foo.com
, which uses cookie-based session authentication. Your dashboard API routes are hosted at dash.foo.com/api
. You want to set up personalization for your docs hosted at foo.com/docs
.
Setup process:
- Create endpoint
dash.foo.com/api/docs/user-info
that identifies users via session authentication and responds with their user data. - Add CORS headers for this route only:
Access-Control-Allow-Origin
:https://foo.com
Access-Control-Allow-Credentials
:true
- Configure API URL in authentication settings:
https://dash.foo.com/api/docs/user-info
.
Dashboard at root, docs at root
You have a dashboard at foo.com/dashboard
, which uses cookie-based session authentication. Your dashboard API routes are hosted at foo.com/api
. You want to set up personalization for your docs hosted at foo.com/docs
.
Setup process:
- Create endpoint
foo.com/api/docs/user-info
that identifies users via session authentication and responds with their user data. - Configure API URL in authentication settings:
https://foo.com/api/docs/user-info
No CORS configuration is needed since the dashboard and docs share the same domain.