You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: 'Integrate with your OAuth server to enable user login via the PKCE flow'
3
+
description: 'Enable user login via OAuth PKCE flow'
4
4
---
5
5
6
-
If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience.
6
+
Integrate your existing OAuth server with Mintlify to enable user authentication.
7
7
8
-
## Implementation
8
+
## Setup Steps
9
9
10
10
<Steps>
11
-
<Steptitle="Create your Info API">
12
-
Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [UserInfo](./sending-data) format. Take note of the scope or scopes required to access this endpoint.
11
+
<Steptitle="Create Info API">
12
+
Create an API endpoint that accepts an OAuth access token and returns user information in the [UserInfo](./sending-data) format.
13
13
</Step>
14
-
<Steptitle="Configure your User Auth settings">
15
-
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication), select the OAuth option, and fill out the required fields:
16
-
17
-
-**Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters.
18
-
-**Client ID**: An ID for the OAuth 2.0 client to be used.
19
-
-**Scopes**: An array of scopes that will be requested.
20
-
-**Token URL**: The base URL for the token exchange request.
21
-
-**Info API URL**: The endpoint that will be hit to retrieve user info.
14
+
<Steptitle="Configure OAuth Settings">
15
+
In your [Mintlify dashboard](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication), select OAuth and configure:
16
+
- Authorization URL
17
+
- Client ID
18
+
- Required scopes
19
+
- Token URL
20
+
- Info API URL
22
21
</Step>
23
-
<Steptitle="Configure your OAuth client">
24
-
Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add it as an authorized redirect URL for your OAuth server.
22
+
<Steptitle="Add Redirect URL">
23
+
Add the Redirect URL from your Mintlify dashboard to your OAuth server's authorized redirects.
25
24
</Step>
26
25
</Steps>
27
26
28
-
## Example
29
-
30
-
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`.
31
-
32
-
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.
33
-
34
-
I then go to the Mintlify dashboard settings, navigate to the User Auth settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
-**Info API URL**: `https://api.foo.com/docs/user-info`
40
-
41
-
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.
description: 'Seamlessly share user sessions between your dashboard and your docs'
3
+
description: 'Share user sessions between your dashboard and docs'
4
4
---
5
5
6
-
This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience.
6
+
Share your existing user sessions between your dashboard and documentation for a seamless experience.
7
7
8
-
## Implementation
8
+
## Setup
9
9
10
10
<Steps>
11
-
<Steptitle="Create your Info API">
12
-
Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [UserInfo](./sending-data) format.
13
-
14
-
If the API domain does not *exactly match* the docs domain:
15
-
- Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`)
16
-
- Ensure your API’s `Access-Control-Allow-Credentials` header is `true`
17
-
<Warning>
18
-
These CORS options only need to be enabled on the *single endpoint* responsible for returning user information. We do not recommend enabling these options on all dashboard endpoints.
19
-
</Warning>
11
+
<Steptitle="Create User Info API">
12
+
Create an API endpoint that:
13
+
- Uses your existing session authentication
14
+
- Returns user data in the [UserInfo](./sending-data) format
15
+
- Sets proper CORS headers if your API and docs domains differ:
16
+
- `Access-Control-Allow-Origin`: Set to your docs domain
17
+
- `Access-Control-Allow-Credentials`: Set to `true`
20
18
</Step>
21
-
<Steptitle="Configure your User Auth settings">
22
-
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add the API URL and your Login URL to your User Auth settings.
19
+
<Steptitle="Configure Settings">
20
+
Add your API URL and Login URL in your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication).
23
21
</Step>
24
22
</Steps>
25
23
26
-
## Examples
27
-
28
-
### Dashboard at subdomain, docs at subdomain
29
-
30
-
I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `docs.foo.com`.
31
-
32
-
To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://docs.foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true`**for this route only**.
33
-
34
-
I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field.
35
-
36
-
### Dashboard at subdomain, docs at root
37
-
38
-
I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`.
39
-
40
-
To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true`**for this route only**.
41
-
42
-
I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field.
43
-
44
-
### Dashboard at root, docs at root
24
+
## Common Setups
45
25
46
-
I have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. My dashboard API routes are hosted at `foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`.
26
+
1.**Docs and Dashboard on Subdomains**
27
+
- Dashboard: `dash.foo.com`
28
+
- Docs: `docs.foo.com`
29
+
- API Endpoint: `dash.foo.com/api/docs/user-info`
47
30
48
-
To set up authentication with Mintlify, I create another dashboard endpoint `foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification.
31
+
2.**Dashboard on Subdomain, Docs on Root**
32
+
- Dashboard: `dash.foo.com`
33
+
- Docs: `foo.com/docs`
34
+
- API Endpoint: `dash.foo.com/api/docs/user-info`
49
35
50
-
I then go to the Mintlify dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field.
Add the widget by adding these script tags into your site's `<head>...<head/>` tag.
11
+
1. Get your API key from the [Mintlify dashboard](https://dashboard.mintlify.com/chat/widget-auth)
12
+
2. Add the widget to your site:
18
13
14
+
### HTML Installation
19
15
```html
20
16
<script>
21
17
window.mintlifyWidgetSettings= {
@@ -37,8 +33,7 @@ Add the widget by adding these script tags into your site's `<head>...<head/>` t
37
33
</script>
38
34
```
39
35
40
-
To use the widget in React and Next.js apps, use the React component from the `@mintlify/widget-react`[package](https://www.npmjs.com/package/@mintlify/widget-react). Here is a basic example of how to use the component in your React application:
41
-
36
+
### React Installation
42
37
```jsx
43
38
<MintlifyWidget
44
39
connection={{
@@ -47,73 +42,14 @@ To use the widget in React and Next.js apps, use the React component from the `@
47
42
/>
48
43
```
49
44
50
-
## Usage
51
-
52
-
In the first script tag or the React component props, you can customize the appearance and other settings of the widget. `mintlifyWidgetSettings` accepts the following props:
Copy file name to clipboardExpand all lines: api-playground/mdx/configuration.mdx
+14-25Lines changed: 14 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,25 +3,24 @@ title: 'MDX Setup'
3
3
description: 'Generate docs pages for your API endpoints using MDX'
4
4
---
5
5
6
-
Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
6
+
Mintlify helps you create interactive API documentation using MDX. Here's how to get started:
7
7
8
8
<Steps>
9
-
<Steptitle="Configure your API">
10
-
In your `mint.json` file, define your base URL and auth method:
9
+
<Steptitle="Configure API in mint.json">
10
+
Add your API configuration to `mint.json`:
11
11
12
12
```json
13
13
{
14
14
"api": {
15
-
"baseUrl": "https://mintlify.com/api",// string array for multiple base URLs
15
+
"baseUrl": "https://mintlify.com/api",
16
16
"auth": {
17
-
"method": "bearer"// options: bearer, basic, key.
17
+
"method": "bearer"
18
18
}
19
19
}
20
20
}
21
21
```
22
22
23
-
If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field:
24
-
23
+
To hide the API playground, use:
25
24
```json
26
25
{
27
26
"api": {
@@ -31,35 +30,25 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
31
30
}
32
31
}
33
32
```
34
-
35
-
Find a full list of API configurations [here](/settings/global#api-configurations).
36
33
</Step>
37
34
38
-
<Steptitle="Create your endpoint pages">
39
-
40
-
Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
35
+
<Steptitle="Create endpoint pages">
36
+
Create MDX files for each endpoint with the required metadata:
41
37
42
38
```md
43
39
---
44
40
title: 'Create new user'
45
-
api: 'POST https://api.mintlify.com/user'
41
+
api: 'POST /user'
46
42
---
47
43
```
48
44
49
-
You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:
50
-
45
+
For paths with parameters, use `{paramName}` syntax:
51
46
```bash
52
-
https://api.example.com/v1/endpoint/{userId}
47
+
/v1/endpoint/{userId}
53
48
```
54
-
55
-
<Note>
56
-
57
-
If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`.
58
-
59
-
</Note>
60
49
</Step>
61
50
62
-
<Steptitle="Add your endpoints to your docs">
63
-
Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation).
51
+
<Steptitle="Add to navigation">
52
+
Add your endpoint pages to the `navigation` field in `mint.json` to display them in your sidebar.
![mintlify-development[bot]](https://avatars.githubusercontent.com/in/222252?v=4&size=40){kind=avatar}
0 commit comments