Shared Session Auth
Seamlessly share user sessions between your dashboard and your docs
This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience.
Implementation
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-Originheader (must not be*) - Ensure your API’s
Access-Control-Allow-Credentialsheader istrue
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.
Configure your User Auth settings
Go to your Mintlify dashboard settings and add the API URL and your Login URL to your User Auth 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.
Was this page helpful?