Choosing an Auth Method

How to decide which auth method is right for your docs

Before your users can access personalized content, they must be authenticated. Mintlify supports two methods of authenticating users:

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.

Prerequisites

Shared Session

• 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

JWT

• 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.

Pros & Cons

Shared Session

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

JWT

Pros:

• No dashboard needed
• Reduced risk of API endpoint abuse
• Zero CORS configuration

Cons:

• Must build new functionality around 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