diff --git a/docs.json b/docs.json index ef20fc512..663f3a6f9 100644 --- a/docs.json +++ b/docs.json @@ -97,7 +97,7 @@ "api-playground/troubleshooting" ] }, - { + { "group": "Authentication and Personalization", "pages": [ "settings/authentication-personalization/authentication", @@ -155,7 +155,6 @@ "advanced/dashboard/sso", "advanced/dashboard/permissions", "advanced/dashboard/roles" - ] } ] @@ -214,7 +213,7 @@ { "group": "Version Control and CI/CD", "pages": [ - "settings/github", + "settings/github", "settings/gitlab", "settings/ci", "settings/preview-deployments" diff --git a/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx index c3f7afd6e..d7d5e5106 100644 --- a/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx +++ b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx @@ -81,4 +81,4 @@ Before your users can access personalized content, they must be authenticated. M - Requires all docs readers to have an account in your Mintlify dashboard - + \ No newline at end of file diff --git a/settings/authentication-personalization/authentication-setup/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx index 985ab2a91..75013ad63 100644 --- a/settings/authentication-personalization/authentication-setup/jwt.mdx +++ b/settings/authentication-personalization/authentication-setup/jwt.mdx @@ -7,7 +7,7 @@ description: 'Use a customized login flow to authenticate users' This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different. -If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL. +If you don't have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL. ## Implementation @@ -30,12 +30,12 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs ## Example I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs -to be completely separate from my dashboard (or I don’t have a dashboard at all). +to be completely separate from my dashboard (or I don't have a dashboard at all). To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow for my users. At the end of this login flow, once I have verified the identity of the user, -I create a JWT containing the user’s custom data according to Mintlify’s specification. +I create a JWT containing the user's custom data according to Mintlify's specification. I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user. @@ -116,4 +116,4 @@ Example: * Redirect to login: [`https://foo.com/docs-login?redirect=%2Fquickstart`](https://foo.com/docs-login?redirect=%2Fquickstart) After successful authentication, you can include this same `redirect` parameter in your JWT callback URL to send users to their intended destination: -`https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}` +`https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}` \ No newline at end of file diff --git a/settings/authentication-personalization/authentication-setup/mintlify.mdx b/settings/authentication-personalization/authentication-setup/mintlify.mdx index 5e9140785..729960d32 100644 --- a/settings/authentication-personalization/authentication-setup/mintlify.mdx +++ b/settings/authentication-personalization/authentication-setup/mintlify.mdx @@ -43,4 +43,4 @@ my [dashboard settings](https://dashboard.mintlify.com/settings/organization/mem been added as users in your [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/organization/members). - + \ No newline at end of file diff --git a/settings/authentication-personalization/authentication-setup/oauth.mdx b/settings/authentication-personalization/authentication-setup/oauth.mdx index b126c487e..376c6afae 100644 --- a/settings/authentication-personalization/authentication-setup/oauth.mdx +++ b/settings/authentication-personalization/authentication-setup/oauth.mdx @@ -37,7 +37,7 @@ If you have an existing OAuth server, you can integrate with Mintlify for a seam 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. +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 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` @@ -46,4 +46,4 @@ I then go to the dashboard settings, navigate to the Authentication settings, se - **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. +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. \ No newline at end of file diff --git a/settings/authentication-personalization/authentication-setup/password.mdx b/settings/authentication-personalization/authentication-setup/password.mdx index c68a0f886..f0600bbb6 100644 --- a/settings/authentication-personalization/authentication-setup/password.mdx +++ b/settings/authentication-personalization/authentication-setup/password.mdx @@ -40,4 +40,4 @@ enough for my team. To set up authentication with Mintlify, I go to my Mintlify dashboard and add at least one password. I then share that password, along with the private docs URL, -with potential customers. +with potential customers. \ No newline at end of file diff --git a/settings/authentication-personalization/authentication.mdx b/settings/authentication-personalization/authentication.mdx index 94786d377..c4295a7d7 100644 --- a/settings/authentication-personalization/authentication.mdx +++ b/settings/authentication-personalization/authentication.mdx @@ -28,4 +28,4 @@ Authentication is similar to our [Personalization](./personalization) offering, to securing your documentation content, all features that are available via Personalization are also available via Authentication. -Check out our docs for more info on [choosing Authentication vs Personalization](./authentication-vs-personalization). +Check out our docs for more info on [choosing Authentication vs Personalization](./authentication-vs-personalization). \ No newline at end of file diff --git a/settings/authentication-personalization/partial-authentication.mdx b/settings/authentication-personalization/partial-authentication.mdx index b27f15ad5..19c1bb250 100644 --- a/settings/authentication-personalization/partial-authentication.mdx +++ b/settings/authentication-personalization/partial-authentication.mdx @@ -22,4 +22,4 @@ By default, all pages are protected. You can specify which pages should be publi title: "My Page" public: true --- -``` +``` \ No newline at end of file diff --git a/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx b/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx index 9c7823cc3..1e1dc6174 100644 --- a/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx +++ b/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx @@ -82,4 +82,4 @@ Before your users can access personalized content, they must be authenticated. M - Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately - Might be overkill for some applications - + \ No newline at end of file diff --git a/settings/authentication-personalization/personalization-setup/jwt.mdx b/settings/authentication-personalization/personalization-setup/jwt.mdx index 00558b3d9..62036f678 100644 --- a/settings/authentication-personalization/personalization-setup/jwt.mdx +++ b/settings/authentication-personalization/personalization-setup/jwt.mdx @@ -8,7 +8,7 @@ description: 'Use a customized login flow to authenticate users' -If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to send user info to your docs via a JWT in the URL. +If you don't have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to send user info to your docs via a JWT in the URL. ## Implementation @@ -31,12 +31,12 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs ## Example I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs -to be completely separate from my dashboard (or I don’t have a dashboard at all). +to be completely separate from my dashboard (or I don't have a dashboard at all). To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow for my users. At the end of this login flow, once I have verified the identity of the user, -I create a JWT containing the user’s custom data according to Mintlify’s specification. +I create a JWT containing the user's custom data according to Mintlify's specification. I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the form `https://docs.foo.com#{SIGNED_JWT}`, and redirect the user. @@ -80,4 +80,4 @@ Post-login, if you'd like to redirect to a specific anchor on the page, you can Example: - Original: `https://docs.foo.com/quickstart#step-one` -- Redirect: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one` +- Redirect: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one` \ No newline at end of file diff --git a/settings/authentication-personalization/personalization-setup/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx index d72f1be27..8d238279b 100644 --- a/settings/authentication-personalization/personalization-setup/oauth.mdx +++ b/settings/authentication-personalization/personalization-setup/oauth.mdx @@ -33,7 +33,7 @@ If you have an existing OAuth server that supports the PKCE flow, you can integr 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. +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 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` @@ -42,4 +42,4 @@ I then go to the dashboard settings, navigate to the Personalization settings, s - **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. +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. \ No newline at end of file diff --git a/settings/authentication-personalization/personalization-setup/shared-session.mdx b/settings/authentication-personalization/personalization-setup/shared-session.mdx index a849cbcfc..80f163724 100644 --- a/settings/authentication-personalization/personalization-setup/shared-session.mdx +++ b/settings/authentication-personalization/personalization-setup/shared-session.mdx @@ -7,7 +7,7 @@ description: 'Seamlessly share user sessions between your dashboard and your doc This is the documentation for the Shared Session **Personalization** Handshake. The Shared Session Handshake is not available for Authentication. -This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience. +This method utilizes the session authentication info already stored in your user's browser to create a seamless documentation experience. ## Implementation @@ -17,7 +17,7 @@ This method utilizes the session authentication info already stored in your user If the API domain does not *exactly match* the docs domain: - Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`) - - Ensure your API’s `Access-Control-Allow-Credentials` header is `true` + - Ensure your API's `Access-Control-Allow-Credentials` header is `true` 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. @@ -33,7 +33,7 @@ This method utilizes the session authentication info already stored in your user 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`. -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**. +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**. I then go to the dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field. @@ -41,7 +41,7 @@ I then go to the dashboard settings and enter `https://dash.foo.com/api/docs/use 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`. -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**. +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**. I then go to the dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field. @@ -49,6 +49,6 @@ I then go to the dashboard settings and enter `https://dash.foo.com/api/docs/use 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`. -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. +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. I then go to the dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field. \ No newline at end of file diff --git a/settings/authentication-personalization/personalization.mdx b/settings/authentication-personalization/personalization.mdx index 83baa4bb1..10f83775b 100644 --- a/settings/authentication-personalization/personalization.mdx +++ b/settings/authentication-personalization/personalization.mdx @@ -30,7 +30,7 @@ This feature becomes even more powerful when paired with custom data about the u Personalization is an enterprise feature. { user.org === undefined -? <>To access this feature, first create an account at the Mintlify dashboard. +? <>To access this feature, first create an account. : user.org.plan !== 'enterprise' ? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. : <>To request this feature for your enterprise org, contact our team. @@ -39,7 +39,7 @@ user.org === undefined ```jsx Personalization is an enterprise feature. { user.org === undefined - ? <>To access this feature, first create an account at the Mintlify dashboard. + ? <>To access this feature, first create an account. : user.org.plan !== 'enterprise' ? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. : <>To request this feature for your enterprise org, contact our team. @@ -82,4 +82,4 @@ Here's a table that displays whether a page is shown for different combinations Note that an empty array in the page metadata is interpreted as "No groups should see this page." - + \ No newline at end of file diff --git a/settings/authentication-personalization/sending-data.mdx b/settings/authentication-personalization/sending-data.mdx index 4fb4b4165..8ba9fb57a 100644 --- a/settings/authentication-personalization/sending-data.mdx +++ b/settings/authentication-personalization/sending-data.mdx @@ -31,7 +31,7 @@ type User = { path="groups" type="string[]" > - 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 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. 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. - - - \ No newline at end of file + \ No newline at end of file