Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@
"api-playground/troubleshooting"
]
},
{
{
"group": "Authentication and Personalization",
"pages": [
"settings/authentication-personalization/authentication",
Expand Down Expand Up @@ -155,7 +155,6 @@
"advanced/dashboard/sso",
"advanced/dashboard/permissions",
"advanced/dashboard/roles"

]
}
]
Expand Down Expand Up @@ -214,7 +213,7 @@
{
"group": "Version Control and CI/CD",
"pages": [
"settings/github",
"settings/github",
"settings/gitlab",
"settings/ci",
"settings/preview-deployments"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
</Tab>
</Tabs>
</Tabs>
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
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.
</Info>

If you dont 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

Expand All @@ -30,12 +30,12 @@
## 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 dont 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 users custom data according to Mintlifys 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.

Expand All @@ -46,20 +46,20 @@

<CodeGroup>
```ts TypeScript
import * as jose from 'jose';

Check warning on line 49 in settings/authentication-personalization/authentication-setup/jwt.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

settings/authentication-personalization/authentication-setup/jwt.mdx#L49

Did you really mean 'jose'?
import { Request, Response } from 'express';

const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;

const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');

Check warning on line 54 in settings/authentication-personalization/authentication-setup/jwt.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

settings/authentication-personalization/authentication-setup/jwt.mdx#L54

Did you really mean 'signingKey'?

export async function handleRequest(req: Request, res: Response) {
const user = {
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
groups: res.locals.user.groups,
content: {
firstName: res.locals.user.firstName,

Check warning on line 61 in settings/authentication-personalization/authentication-setup/jwt.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

settings/authentication-personalization/authentication-setup/jwt.mdx#L61

Did you really mean 'firstName'?
lastName: res.locals.user.lastName,

Check warning on line 62 in settings/authentication-personalization/authentication-setup/jwt.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

settings/authentication-personalization/authentication-setup/jwt.mdx#L62

Did you really mean 'lastName'?
},
};

Expand Down Expand Up @@ -116,4 +116,4 @@
* 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}`
Original file line number Diff line number Diff line change
Expand Up @@ -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).
</Step>
</Steps>
</Steps>
Original file line number Diff line number Diff line change
Expand Up @@ -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 Mintlifys 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`
Expand All @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion settings/authentication-personalization/authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,11 @@

Partial Authentication shares all the same features as [Authentication](./authentication), but with the ability to allow unauthenticated users to view certain pages.

By default, all pages are protected. You can specify which pages should be publicly accessible by adding the `public` property to the page's frontmatter.

Check warning on line 18 in settings/authentication-personalization/partial-authentication.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

settings/authentication-personalization/partial-authentication.mdx#L18

Did you really mean 'frontmatter'?

```mdx
---
title: "My Page"
public: true
---
```
```
Original file line number Diff line number Diff line change
Expand Up @@ -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
</Tab>
</Tabs>
</Tabs>
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ description: 'Use a customized login flow to authenticate users'
</Info>


If you dont 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

Expand All @@ -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 dont 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 users custom data according to Mintlifys 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.

Expand Down Expand Up @@ -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`
Original file line number Diff line number Diff line change
Expand Up @@ -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 Mintlifys 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`
Expand All @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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.
</Info>

This method utilizes the session authentication info already stored in your users 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

Expand All @@ -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 APIs `Access-Control-Allow-Credentials` header is `true`
- Ensure your API's `Access-Control-Allow-Credentials` header is `true`
<Warning>
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.
</Warning>
Expand All @@ -33,22 +33,22 @@ 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 Mintlifys 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.

### Dashboard at subdomain, docs at root

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 Mintlifys 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.

### Dashboard at root, docs at root

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 Mintlifys 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.
6 changes: 3 additions & 3 deletions settings/authentication-personalization/personalization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

- **Customize MDX content** with a user's information, such as their name, plan, or title.

- **Prefill API keys** in the API Playground for streamlined use.

Check warning on line 13 in settings/authentication-personalization/personalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

settings/authentication-personalization/personalization.mdx#L13

Did you really mean 'Prefill'?

- **Selectively show pages** in the navigation based on a user's groups.

Expand All @@ -30,7 +30,7 @@

Personalization is an enterprise feature. {
user.org === undefined
? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
? <>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, <a href="mailto:[email protected]">contact our sales team</a>.</>
: <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
Expand All @@ -39,7 +39,7 @@
```jsx
Personalization is an enterprise feature. {
user.org === undefined
? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
? <>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, <a href="mailto:[email protected]">contact our sales team</a>.</>
: <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
Expand All @@ -53,9 +53,9 @@
fields, e.g. `{user.org?.plan}`
</Note>

### Prefilling API Keys

Check warning on line 56 in settings/authentication-personalization/personalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

settings/authentication-personalization/personalization.mdx#L56

Did you really mean 'Prefilling'?

If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground.

Check warning on line 58 in settings/authentication-personalization/personalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

settings/authentication-personalization/personalization.mdx#L58

Did you really mean 'prefilled'?

### Showing/Hiding Pages

Expand All @@ -82,4 +82,4 @@
<Note>
Note that an empty array in the page metadata is interpreted as "No groups
should see this page."
</Note>
</Note>
6 changes: 2 additions & 4 deletions settings/authentication-personalization/sending-data.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
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 pages 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.
</ParamField>
<ParamField
path="content"
Expand All @@ -43,9 +43,7 @@
path="apiPlaygroundInputs"
type="object"
>
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.

Check warning on line 46 in settings/authentication-personalization/sending-data.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

settings/authentication-personalization/sending-data.mdx#L46

Did you really mean 'prefilled'?

Check warning on line 46 in settings/authentication-personalization/sending-data.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

settings/authentication-personalization/sending-data.mdx#L46

Did you really mean 'prefilled'?

<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>
</ParamField>


</ParamField>