Skip to main content
This is the documentation for the OAuth Personalization Handshake. The steps for setting up the OAuth Authentication Handshake are slightly different.
If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience.

​
Implementation

1

Create your Info API

Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the User format. Take note of the scope or scopes required to access this endpoint.
2

Configure your Personalization settings

Go to your dashboard settings, select the OAuth option, and fill out the required fields:
  • Authorization URL: The base URL for the authorization request, to which we will add the appropriate query parameters.
  • Client ID: An ID for the OAuth 2.0 client to be used.
  • Scopes: An array of scopes that will be requested.
  • Token URL: The base URL for the token exchange request.
  • Info API URL: The endpoint that will be hit to retrieve user info.
3

Configure your OAuth client

Copy the Redirect URL listed in the dashboard settings and add it as an authorized redirect URL for your OAuth server.

​
Example

I have an existing OAuth server that supports the PKCE flow. I want to set up authentication for my docs hosted at foo.com/docs. To set up authentication with Mintlify, I create an endpoint api.foo.com/docs/user-info which requires an OAuth access token with the docs-user-info scope, and responds with the user’s custom data according to Mintlify’s specification. I then go to the dashboard settings, navigate to the Personalization settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
  • Authorization URL: https://auth.foo.com/authorization
  • Client ID: ydybo4SD8PR73vzWWd6S0ObH
  • Scopes: ['docs-user-info']
  • Token URL: https://auth.foo.com/exchange
  • Info API URL: https://api.foo.com/docs/user-info
Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings.
⌘I