Shared Session Handshake

Seamlessly share user sessions between your dashboard and your docs

This is the documentation for the Shared Session Personalization Handshake. The Shared Session Handshake is not available for Authentication.

This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience.

Implementation

1. Create your Info API

   Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the UserInfo format.

   If the API domain does not exactly match the docs domain:

   • Add the docs domain to your API’s Access-Control-Allow-Origin header (must not be *)
   • Ensure your API’s Access-Control-Allow-Credentials header is true

   These CORS options only need to be enabled on the single endpoint responsible for returning user information. We do not recommend enabling these options on all dashboard endpoints.

2. Configure your Personalization settings

   Go to your Mintlify dashboard settings and add the API URL and your Login URL to your Personalization settings.

Examples

Dashboard at subdomain, docs at subdomain

I have a dashboard at dash.foo.com, which uses cookie-based session authentication. My dashboard API routes are hosted at dash.foo.com/api. I want to set up authentication for my docs hosted at docs.foo.com.

To set up authentication with Mintlify, I create another dashboard endpoint dash.foo.com/api/docs/user-info which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add https://docs.foo.com to the Access-Control-Allow-Origin allow-list for this route only, and ensure my Access-Control-Allow-Credentials configuration is set to true for this route only.

I then go to the Mintlify dashboard settings and enter https://dash.foo.com/api/docs/user-info for the API URL field.

Dashboard at subdomain, docs at root

I have a dashboard at dash.foo.com, which uses cookie-based session authentication. My dashboard API routes are hosted at dash.foo.com/api. I want to set up authentication for my docs hosted at foo.com/docs.

To set up authentication with Mintlify, I create another dashboard endpoint dash.foo.com/api/docs/user-info which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add https://foo.com to the Access-Control-Allow-Origin allow-list for this route only, and ensure my Access-Control-Allow-Credentials configuration is set to true for this route only.

I then go to the Mintlify dashboard settings and enter https://dash.foo.com/api/docs/user-info for the API URL field.

Dashboard at root, docs at root

I have a dashboard at foo.com/dashboard, which uses cookie-based session authentication. My dashboard API routes are hosted at foo.com/api. I want to set up authentication for my docs hosted at foo.com/docs.

To set up authentication with Mintlify, I create another dashboard endpoint foo.com/api/docs/user-info which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification.

I then go to the Mintlify dashboard settings and enter https://foo.com/api/docs/user-info for the API URL field.