OAuth 2.0 Handshake
Integrate with your OAuth server to enable user login via the PKCE flow
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
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 UserInfo format. Take note of the scope or scopes required to access this endpoint.
Configure your Personalization settings
Go to your Mintlify 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.
Configure your OAuth client
Copy the Redirect URL listed in the Mintlify 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 Mintlify 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.
Was this page helpful?