This is the documentation for Personalization Handshake methods. Authentication offers a different set of Handshake methods.

Before your users can access personalized content, they must be authenticated. Mintlify supports three Personalization Handshake methods:

  1. Shared Session: Utilize the same session token used by your dashboard to authenticate users.
  2. JWT: Use your own login flow to send user info to your docs via a JWT in the URL.
  3. 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

​
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

Was this page helpful?

Mintlify Dashboard HandshakeShared Session Handshake