This is the documentation for the OAuth Authentication Handshake. The steps for setting up the OAuth Personalization Handshake are slightly different.

If you have an existing OAuth server, you can integrate with Mintlify for a seamless login experience.

​
Implementation

1

Configure your Authentication settings

Go to your Mintlify authentication 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 (optional): The endpoint that will be hit to retrieve user info. If omitted, the OAuth flow will only be used to verify identity, and the user info will be empty.
2

Configure your OAuth client

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

3

Create your Info API (Optional)

If you want to take advantage of authentication’s customization features, you’ll need to create an endpoint to retrieve info about your users. Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the UserInfo format.

Return to your Mintlify authentication settings and add the Info API URL to your OAuth configuration.

​
Example

I have an existing OAuth server that supports the Authorization Code 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 Mintlify dashboard settings, navigate to the Authentication 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.

Was this page helpful?

JWT HandshakeMintlify Dashboard Handshake