Before your users can access personalized content, they must be authenticated. Mintlify supports three Personalization Handshake methods:
- Shared Session: Utilize the same session token used by your dashboard to authenticate users.
- JWT: Use your own login flow to send user info to your docs via a JWT in the URL.
- OAuth 2.0: Integrate with your OAuth server to enable user login via the PKCE flow.
Prerequisites
- You have a dashboard or other user portal hosted at your domain.
- Your users’ session credentials are stored as cookies.
- You can create a new API endpoint at the same origin or a subdomain of your dashboard.
- If your dashboard is at
foo.com, the API URL must start with foo.com or *.foo.com
- If your dashboard is at
dash.foo.com, the API URL must start with dash.foo.com or *.dash.foo.com
- Your docs are hosted at the same domain as your dashboard.
- If your dashboard is at
foo.com, your docs must be hosted at foo.com or *.foo.com
- If your dashboard is at
*.foo.com, your docs must be hosted at foo.com or *.foo.com
- You have a dashboard or other user portal hosted at your domain.
- Your users’ session credentials are stored as cookies.
- You can create a new API endpoint at the same origin or a subdomain of your dashboard.
- If your dashboard is at
foo.com, the API URL must start with foo.com or *.foo.com
- If your dashboard is at
dash.foo.com, the API URL must start with dash.foo.com or *.dash.foo.com
- Your docs are hosted at the same domain as your dashboard.
- If your dashboard is at
foo.com, your docs must be hosted at foo.com or *.foo.com
- If your dashboard is at
*.foo.com, your docs must be hosted at foo.com or *.foo.com
- You have some existing login flow.
- You can add a final step in this login flow that creates a JWT and redirects to the docs.
- You have an existing OAuth server that supports the PKCE flow.
- You can create a new API endpoint that can be accessed by the returned OAuth access token.
Pros & Cons
Pros:
- Users that are logged into your dashboard are automatically logged into your docs
- Your users’ sessions are persistent, meaning you can refresh data without requiring additional login
- Minimal setup required
Cons:
- Your docs will make a request to your backend, which may be undesirable
- You must have a dashboard that uses session authentication
- CORS configuration is usually required
Pros:
- Users that are logged into your dashboard are automatically logged into your docs
- Your users’ sessions are persistent, meaning you can refresh data without requiring additional login
- Minimal setup required
Cons:
- Your docs will make a request to your backend, which may be undesirable
- You must have a dashboard that uses session authentication
- CORS configuration is usually required
Pros:
- Reduced risk of API endpoint abuse
- Zero CORS configuration
- No restrictions on API URLs
Cons:
- Must be able to hook into your existing login flow
- Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately
- Every time you want to refresh user data, your users must re-login to your docs
- If your users’ data changes frequently, you must require your users to log in frequently or risk having stale data in the docs
- If your users’ data rarely changes, this shouldn’t be a problem
Pros:
- Heightened security standard
- No restrictions on API URLs
Cons:
- Requires significant work if setting up OAuth server for the first time
- Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately
- Might be overkill for some applications
