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
Copy file name to clipboardExpand all lines: advanced/dashboard/permissions.mdx
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,14 +3,14 @@ title: 'Editor Permissions'
3
3
description: 'Allow more members of your team to update your docs'
4
4
---
5
5
6
-
The team member who created your initial docs will have update access to your docs, as long as they push to your documentation repo with the same GitHub account that was used while signing up for Mintlify.
6
+
The team member who created your initial documentation will have update access to your docs, provided they push to your documentation repository using the same GitHub account that was used during Mintlify signup.
7
7
8
-
If another editor attempts to update the docs while on the free plan, you will see a warning in your git commit check.
8
+
If another editor attempts to update the docs while on the free plan, a warning will appear in your git commit check.
In the details of the git check warning, you'll find the link to upgrade your plan. You can also upgrade your plan on the [dashboard](https://dashboard.mintlify.com) to enable unlimited editors to update your docs. Once you upgrade your plan, trigger a manual update or push another change to deploy your updates.
14
+
You can find the upgrade link in the details of the git check warning. Alternatively, youcan upgrade your plan directly through the [dashboard](https://dashboard.mintlify.com) to enable unlimited editors for your documentation. After upgrading, either trigger a manual update or push a new change to deploy your updates.
15
15
16
-
Learn more about our pricing [here](https://mintlify.com/pricing).
16
+
To learn more about our pricing options, visit our [pricing page](https://mintlify.com/pricing).
Copy file name to clipboardExpand all lines: advanced/dashboard/sso.mdx
+17-18Lines changed: 17 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@ title: "Single Sign-On (SSO)"
3
3
description: "Customize how your team can login to your admin dashboard"
4
4
---
5
5
6
-
Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO, but if you use another provider, please contact us!
6
+
Use Single Sign-On (SSO) to access your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO. For other providers, please contact us!
7
7
8
8
<Note>
9
9
SSO functionality is available on our Enterprise plan. [Contact
@@ -16,37 +16,37 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl
16
16
<Tabtitle="SAML">
17
17
<Steps>
18
18
<Steptitle="Create an application">
19
-
Under `Applications`, click to create a new app integration using SAML 2.0.
19
+
Under "Applications," click to create a new app integration using SAML 2.0.
20
20
</Step>
21
21
<Steptitle="Configure integration">
22
-
Enter the following:
23
-
* Single sign-on URL (provided by Mintlify)
22
+
Enter the following information:
23
+
* Single Sign-On URL (provided by Mintlify)
24
24
* Audience URI (provided by Mintlify)
25
25
* Name ID Format: `EmailAddress`
26
26
* Attribute Statements:
27
-
| Name | Name format | Value
28
-
| ---- | ----------- | -----
27
+
| Name | Name format | Value |
28
+
| ---- | ----------- | ----- |
29
29
| `firstName` | Basic | `user.firstName` |
30
30
| `lastName` | Basic | `user.lastName` |
31
31
</Step>
32
32
<Steptitle="Send us your IdP information">
33
-
Once the application is set up, navigate to the sign-on tab and send us the metadata URL.
33
+
Once the application is set up, navigate to the Sign-On tab and send us the metadata URL.
34
34
We'll enable the connection from our side using this information.
35
35
</Step>
36
36
</Steps>
37
37
</Tab>
38
38
<Tabtitle="OIDC">
39
39
<Steps>
40
40
<Steptitle="Create an application">
41
-
Under `Applications`, click to create a new app integration using OIDC.
42
-
You should choose the `Web Application` application type.
41
+
Under "Applications," click to create a new app integration using OIDC.
42
+
Choose the "Web Application" application type.
43
43
</Step>
44
44
<Steptitle="Configure integration">
45
45
Select the authorization code grant type and enter the Redirect URI provided by Mintlify.
46
46
</Step>
47
47
<Steptitle="Send us your IdP information">
48
-
Once the application is set up, navigate to the General tab and locate the client ID & client secret.
49
-
Please securely provide us with these, along with your Okta instance URL (e.g. `<your-tenant-name>.okta.com`). You can send these via a service like 1Password or SendSafely.
48
+
Once the application is set up, navigate to the General tab and locate the Client ID & Client Secret.
49
+
Please securely provide us with these credentials, along with your Okta instance URL (e.g.,`<your-tenant-name>.okta.com`). You can send these via a service like 1Password or SendSafely.
50
50
</Step>
51
51
</Steps>
52
52
</Tab>
@@ -58,19 +58,19 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl
58
58
<Tabtitle="SAML">
59
59
<Steps>
60
60
<Steptitle="Create an application">
61
-
Under `Web and mobile apps`, select `Add custom SAML app` from the `Add app` dropdown.
61
+
Under "Web and mobile apps," select "Add custom SAML app" from the "Add app" dropdown.
62
62
<Frame>
63
63
64
64
</Frame>
65
65
</Step>
66
66
<Steptitle="Send us your IdP information">
67
-
Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team.
67
+
Copy the provided SSO URL, Entity ID, and X.509 certificate and send them to the Mintlify team.
68
68
<Frame>
69
69
70
70
</Frame>
71
71
</Step>
72
72
<Steptitle="Configure integration">
73
-
On the Service provider details page, enter the following:
73
+
On the Service Provider Details page, enter the following information:
74
74
* ACS URL (provided by Mintlify)
75
75
* Entity ID (provided by Mintlify)
76
76
* Name ID format: `EMAIL`
@@ -83,12 +83,11 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl
83
83
On the next page, enter the following attribute statements:
84
84
| Google Directory Attribute | App Attribute |
85
85
| -------------------------- | ------------- |
86
-
| `First name` | `firstName`|
86
+
| `First name` | `firstName` |
87
87
| `Last name` | `lastName` |
88
88
89
-
Once this step is complete and users are assigned to the application, let our team know and we'll enable SSO for your account!
89
+
Once this step is complete and users are assigned to the application, let our team know, and we'll enable SSO for your account!
Copy file name to clipboardExpand all lines: advanced/rest-api/overview.mdx
+11-12Lines changed: 11 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,39 +4,38 @@ title: Overview
4
4
5
5
## Trigger Updates
6
6
7
-
You can leverage the REST API to programmatically trigger an update when desired.
7
+
You can leverage the REST API to programmatically trigger updates when desired.
8
8
9
9
<Info>
10
-
While the primary use-case will be to trigger updates, we will be adding more and more
11
-
functionality to the API overtime. Let us know what else you want to see in
10
+
While the primary use case is triggering updates, we will be adding more functionality to the API over time. Let us know what else you would like to see in
12
11
[our community](https://mintlify.com/community)!
13
12
</Info>
14
13
15
14
## Authentication
16
15
17
16
You can generate an API key through
18
17
[the dashboard](https://dashboard.mintlify.com/settings/organization/api-keys). The API key is
19
-
associated with the entire org and can be used across multiple deployments.
18
+
associated with your entire organization and can be used across multiple deployments.
20
19
21
20
<Frame>
22
21
<imgsrc="/images/external-api-key.png" />
23
22
</Frame>
24
23
25
-
## Admin API key
24
+
## Admin API Key
26
25
27
-
The Admin API key is used for the majority of the API. It is used to trigger updates via the [Update endpoint](/advanced/rest-api/update/trigger).
26
+
The Admin API key is used for the majority of the API endpoints. Its primary use is triggering updates via the [Update endpoint](/advanced/rest-api/update/trigger).
28
27
29
-
## Chat API key
28
+
## Chat API Key
30
29
31
-
The Chat API allows you to embed the AI chat experience grounded in your docs and continually kept up to date into any application of your choosing.
30
+
The Chat API allows you to embed an AI chat experience, grounded in your documentation and continuously kept up to date, into any application of your choosing.
32
31
33
-
Responses include citations so you can point your users to the right places they need to get help.
32
+
Responses include citations, enabling you to direct your users to the specific documentation sections they need.
34
33
35
34
<Note>
36
35
The Chat API token is a public token that can be referenced in your
37
-
frontend code whereas the API key is a server-side token that should be kept
36
+
frontend code, whereas the API key is a server-side token that should be kept
38
37
secret.
39
38
</Note>
40
39
41
-
Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example)for how to use
42
-
the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com).
40
+
Now that you have an API key, check out our [example repository](https://github.com/mintlify/discovery-api-example)to learn how to use
41
+
the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com).
Copy file name to clipboardExpand all lines: api-playground/mdx/configuration.mdx
+13-16Lines changed: 13 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,25 +3,25 @@ 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 `docs.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 allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From these defined endpoints, we generate an API playground, request examples, and response examples.
7
7
8
8
<Steps>
9
9
<Steptitle="Configure your API">
10
-
In your `docs.json` file, define your base URL and auth method:
10
+
In your `docs.json` file, define your base URL and authentication method:
11
11
12
12
```json
13
13
"api": {
14
14
"mdx": {
15
-
"server": "https://mintlify.com/api", // string array for multiple base URLs
15
+
"server": "https://mintlify.com/api", // String array for multiple base URLs
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
+
If you do not want to display an API playground, you can omit the authentication types. To hide the playground, add the following field:
25
25
26
26
```json
27
27
"api": {
@@ -31,12 +31,11 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js
31
31
}
32
32
```
33
33
34
-
Find a full list of API configurations [here](/settings/global#param-api).
34
+
Find a complete list of API configurations [here](/settings/global#param-api).
35
35
</Step>
36
36
37
37
<Steptitle="Create your endpoint pages">
38
-
39
-
Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
38
+
Each API endpoint should have a corresponding MDX file. At the top of each file, define:
40
39
41
40
```md
42
41
---
@@ -45,30 +44,28 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js
45
44
---
46
45
```
47
46
48
-
You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:
47
+
You can specify path parameters by adding the parameter name to the path, wrapped with curly braces `{}`:
49
48
50
49
```bash
51
50
https://api.example.com/v1/endpoint/{userId}
52
51
```
53
52
54
53
<Note>
55
-
56
-
If you have `server` configured in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`.
57
-
54
+
If you have configured `server` in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`.
58
55
</Note>
59
56
60
-
You can also override the globally-defined display mode for the API playground per page by adding `playground` at the top of the MDX file:
57
+
You can also override the globally-defined display mode for the API playground on a per-page basis by adding the `playground` field at the top of the MDX file:
61
58
62
59
```md
63
60
---
64
61
title: 'Create new user'
65
62
api: 'POST https://api.mintlify.com/user'
66
63
playground: 'none'
64
+
---
67
65
```
68
-
69
66
</Step>
70
67
71
68
<Steptitle="Add your endpoints to your docs">
72
-
Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs[here](/settings/navigation).
69
+
Add your endpoint pages to the sidebar by including their paths in the `navigation` field of your `docs.json`. Learn more about structuring your documentation[here](/settings/navigation).
Copy file name to clipboardExpand all lines: settings/authentication-personalization/sending-data.mdx
+14-8Lines changed: 14 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,27 +24,33 @@ type User = {
24
24
type="number"
25
25
>
26
26
The time at which this information should expire, in **seconds since epoch**. If the user loads the page and the current time is after this value, the stored data will be deleted.
27
-
<Warning><b>For JWT Handshakes:</b> This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. The `expiresAt` field determines when retrieved data should be considered stale, and can be anywhere from one day to several weeks.</Warning>
27
+
28
+
<Warning>
29
+
<b>For JWT Handshakes:</b> This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid and should be set as low as possible (typically 10 seconds or lower). The `expiresAt` field, on the other hand, determines when retrieved data should be considered stale and can be set anywhere from one day to several weeks.
30
+
</Warning>
28
31
</ParamField>
32
+
29
33
<ParamField
30
34
path="groups"
31
35
type="string[]"
32
36
>
33
-
A list of groups that the user belongs to. This will determine which pages should be shown to this user. If any of these groups is listed in the `groups` field of a page’s metadata, that page will be shown.
37
+
A list of groups that the user belongs to. This determines which pages should be shown to this user. If any of these groups is listed in the `groups` field of a page's metadata, that page will be displayed.
34
38
</ParamField>
39
+
35
40
<ParamField
36
41
path="content"
37
42
type="object"
38
43
>
39
-
A bag of values that can be accessed from within MDX content using the `user` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {user.firstName}!`
44
+
A collection of values that can be accessed from within MDX content using the `user` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {user.firstName}!`
40
45
</ParamField>
46
+
41
47
<ParamField
42
48
path="apiPlaygroundInputs"
43
49
type="object"
44
50
>
45
-
User-specific values that will be prefilled in the API playground if supplied. For example, if each of my customers makes requests at a specific subdomain, I can send `{ server: { subdomain: 'foo' } }` as my `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value.
46
-
47
-
<Note>The`header`, `query`, and `cookie` fields will only be prefilled if they are part of your [security scheme](https://swagger.io/docs/specification/authentication/). Creating a standard header parameter named `Authorization` is not sufficient to enable this feature. To know if a field will be prefilled, navigate to your existing docs and check if the field is in either the `Authorization` or `Server` section.</Note>
48
-
</ParamField>
51
+
User-specific values that will be prefilled in the API playground. For example, if each of your customers makes requests at a specific subdomain, you can send `{ server: { subdomain: 'foo' } }` as your `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value.
49
52
50
-
53
+
<Note>
54
+
The `header`, `query`, and `cookie` fields will only be prefilled if they are part of your [security scheme](https://swagger.io/docs/specification/authentication/). Creating a standard header parameter named `Authorization` is not sufficient to enable this feature. To verify if a field will be prefilled, navigate to your existing docs and check if the field appears in either the `Authorization` or `Server` section.
![mintlify[bot]](https://avatars.githubusercontent.com/in/222410?v=4&size=40){kind=avatar}
0 commit comments