diff --git a/advanced/dashboard/permissions.mdx b/advanced/dashboard/permissions.mdx index d39d099a4..9ec61260f 100644 --- a/advanced/dashboard/permissions.mdx +++ b/advanced/dashboard/permissions.mdx @@ -3,14 +3,14 @@ title: 'Editor Permissions' description: 'Allow more members of your team to update your docs' --- -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. +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. -If another editor attempts to update the docs while on the free plan, you will see a warning in your git commit check. +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. +You can find the upgrade link in the details of the git check warning. Alternatively, you can 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. -Learn more about our pricing [here](https://mintlify.com/pricing). +To learn more about our pricing options, visit our [pricing page](https://mintlify.com/pricing). \ No newline at end of file diff --git a/advanced/dashboard/sso.mdx b/advanced/dashboard/sso.mdx index 4a70acc7a..86b112f5c 100644 --- a/advanced/dashboard/sso.mdx +++ b/advanced/dashboard/sso.mdx @@ -3,7 +3,7 @@ title: "Single Sign-On (SSO)" description: "Customize how your team can login to your admin dashboard" --- -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! +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! SSO functionality is available on our Enterprise plan. [Contact @@ -16,21 +16,21 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl - Under `Applications`, click to create a new app integration using SAML 2.0. + Under "Applications," click to create a new app integration using SAML 2.0. - Enter the following: - * Single sign-on URL (provided by Mintlify) + Enter the following information: + * Single Sign-On URL (provided by Mintlify) * Audience URI (provided by Mintlify) * Name ID Format: `EmailAddress` * Attribute Statements: - | Name | Name format | Value - | ---- | ----------- | ----- + | Name | Name format | Value | + | ---- | ----------- | ----- | | `firstName` | Basic | `user.firstName` | | `lastName` | Basic | `user.lastName` | - Once the application is set up, navigate to the sign-on tab and send us the metadata URL. + Once the application is set up, navigate to the Sign-On tab and send us the metadata URL. We'll enable the connection from our side using this information. @@ -38,15 +38,15 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl - Under `Applications`, click to create a new app integration using OIDC. - You should choose the `Web Application` application type. + Under "Applications," click to create a new app integration using OIDC. + Choose the "Web Application" application type. Select the authorization code grant type and enter the Redirect URI provided by Mintlify. - Once the application is set up, navigate to the General tab and locate the client ID & client secret. - Please securely provide us with these, along with your Okta instance URL (e.g. `.okta.com`). You can send these via a service like 1Password or SendSafely. + Once the application is set up, navigate to the General tab and locate the Client ID & Client Secret. + Please securely provide us with these credentials, along with your Okta instance URL (e.g., `.okta.com`). You can send these via a service like 1Password or SendSafely. @@ -58,19 +58,19 @@ Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Googl - Under `Web and mobile apps`, select `Add custom SAML app` from the `Add app` dropdown. + Under "Web and mobile apps," select "Add custom SAML app" from the "Add app" dropdown. ![](/images/gsuite-add-custom-saml-app.png) - Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team. + Copy the provided SSO URL, Entity ID, and X.509 certificate and send them to the Mintlify team. ![](/images/gsuite-saml-metadata.png) - On the Service provider details page, enter the following: + On the Service Provider Details page, enter the following information: * ACS URL (provided by Mintlify) * Entity ID (provided by Mintlify) * 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 On the next page, enter the following attribute statements: | Google Directory Attribute | App Attribute | | -------------------------- | ------------- | - | `First name` | `firstName` | + | `First name` | `firstName` | | `Last name` | `lastName` | - Once this step is complete and users are assigned to the application, let our team know and we'll enable SSO for your account! + Once this step is complete and users are assigned to the application, let our team know, and we'll enable SSO for your account! - - + \ No newline at end of file diff --git a/advanced/rest-api/overview.mdx b/advanced/rest-api/overview.mdx index c1f399434..b8046501d 100644 --- a/advanced/rest-api/overview.mdx +++ b/advanced/rest-api/overview.mdx @@ -4,11 +4,10 @@ title: Overview ## Trigger Updates -You can leverage the REST API to programmatically trigger an update when desired. +You can leverage the REST API to programmatically trigger updates when desired. - While the primary use-case will be to trigger updates, we will be adding more and more - functionality to the API overtime. Let us know what else you want to see in + 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 [our community](https://mintlify.com/community)! @@ -16,27 +15,27 @@ You can leverage the REST API to programmatically trigger an update when desired You can generate an API key through [the dashboard](https://dashboard.mintlify.com/settings/organization/api-keys). The API key is -associated with the entire org and can be used across multiple deployments. +associated with your entire organization and can be used across multiple deployments. -## Admin API key +## Admin API Key -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). +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). -## Chat API key +## Chat API Key -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. +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. -Responses include citations so you can point your users to the right places they need to get help. +Responses include citations, enabling you to direct your users to the specific documentation sections they need. The Chat API token is a public token that can be referenced in your - frontend code whereas the API key is a server-side token that should be kept + frontend code, whereas the API key is a server-side token that should be kept secret. -Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example) for how to use -the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com). +Now that you have an API key, check out our [example repository](https://github.com/mintlify/discovery-api-example) to learn how to use +the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com). \ No newline at end of file diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 9ef4eb106..55119865f 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -3,25 +3,25 @@ title: 'MDX Setup' description: 'Generate docs pages for your API endpoints using MDX' --- -Mintlify allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. +Mintlify allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `` component. From these defined endpoints, we generate an API playground, request examples, and response examples. - In your `docs.json` file, define your base URL and auth method: + In your `docs.json` file, define your base URL and authentication method: ```json "api": { "mdx": { - "server": "https://mintlify.com/api", // string array for multiple base URLs + "server": "https://mintlify.com/api", // String array for multiple base URLs "auth": { "method": "key", - "name": "x-api-key" // options: bearer, basic, key. + "name": "x-api-key" // Options: bearer, basic, key } } } ``` - 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: + If you do not want to display an API playground, you can omit the authentication types. To hide the playground, add the following field: ```json "api": { @@ -31,12 +31,11 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js } ``` - Find a full list of API configurations [here](/settings/global#param-api). + Find a complete list of API configurations [here](/settings/global#param-api). - - Each API endpoint page should have a corresponding MDX file. At the top of each file, define: + Each API endpoint should have a corresponding MDX file. At the top of each file, define: ```md --- @@ -45,30 +44,28 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js --- ``` - You can specify path parameters by adding the parameter name to the path, wrapped with `{}`: + You can specify path parameters by adding the parameter name to the path, wrapped with curly braces `{}`: ```bash https://api.example.com/v1/endpoint/{userId} ``` - - If you have `server` configured in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`. - + If you have configured `server` in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`. - 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: + 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: ```md --- title: 'Create new user' api: 'POST https://api.mintlify.com/user' playground: 'none' + --- ``` - - 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). + 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). - + \ No newline at end of file diff --git a/docs.json b/docs.json index edd11836e..57f8a787f 100644 --- a/docs.json +++ b/docs.json @@ -22,7 +22,10 @@ { "group": "Editing", "icon": "pen-paintbrush", - "pages": ["development", "web-editor"] + "pages": [ + "development", + "web-editor" + ] }, "settings/global", { @@ -69,7 +72,8 @@ "icon": "markdown", "pages": [ "api-playground/mdx/configuration", - "api-playground/mdx/authentication" + "api-playground/mdx/authentication", + "api-playground/mdx/configuration" ] }, "api-playground/troubleshooting" @@ -127,6 +131,7 @@ "settings/authentication-personalization/personalization-setup/oauth" ] }, + "settings/authentication-personalization/sending-data", "settings/authentication-personalization/sending-data" ] }, @@ -135,7 +140,9 @@ "icon": "house-lock", "pages": [ "advanced/dashboard/sso", - "advanced/dashboard/permissions" + "advanced/dashboard/permissions", + "advanced/dashboard/permissions", + "advanced/dashboard/sso" ] }, { @@ -164,7 +171,8 @@ "advanced/rest-api/chat/create-topic", "advanced/rest-api/chat/generate-message" ] - } + }, + "advanced/rest-api/overview" ] } ] @@ -262,7 +270,9 @@ "groups": [ { "group": "Changelog", - "pages": ["changelog/overview"] + "pages": [ + "changelog/overview" + ] } ] } @@ -374,4 +384,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} +} \ No newline at end of file diff --git a/settings/authentication-personalization/sending-data.mdx b/settings/authentication-personalization/sending-data.mdx index e969fa8bc..788d13000 100644 --- a/settings/authentication-personalization/sending-data.mdx +++ b/settings/authentication-personalization/sending-data.mdx @@ -24,27 +24,33 @@ type User = { type="number" > 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. - For JWT Handshakes: 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. + + + For JWT Handshakes: 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. + + - 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. + 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. + - 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}!` + 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}!` + - 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. - - 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. - + 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. - \ No newline at end of file + + 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. + + \ No newline at end of file