> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Choosing a Handshake

> How to decide which Handshake method is right for your docs

<Info>
  This is the documentation for **Personalization** Handshake methods. Authentication offers a [different set of Handshake methods](/settings/authentication-personalization/authentication-setup/choosing-a-handshake).
</Info>

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

<Tabs>
  <Tab title="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`
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="OAuth 2.0">
    * 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.
  </Tab>
</Tabs>

## Pros & Cons

<Tabs>
  <Tab title="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
    * You must have a dashboard that uses session authentication
    * CORS configuration is usually required
  </Tab>

  <Tab title="JWT">
    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
  </Tab>

  <Tab title="OAuth 2.0">
    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
  </Tab>
</Tabs>