Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Replace userContext with User #435

Merged
merged 1 commit into from
Dec 28, 2024
Merged
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
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs
<Step title="Create a login flow">
Create a login flow that does the following:
- Authenticate the user
- Create a JWT containing the authenticated user's info in the [UserInfo](../sending-data) format
- Create a JWT containing the authenticated user's info in the [User](../sending-data) format
- Sign the JWT with the secret key, using the EdDSA algorithm
- Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash
</Step>
Expand Down Expand Up @@ -54,7 +54,7 @@ const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');

export async function handleRequest(req: Request, res: Response) {
const userInfo = {
const user = {
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
groups: res.locals.user.groups,
content: {
Expand All @@ -63,7 +63,7 @@ export async function handleRequest(req: Request, res: Response) {
},
};

const jwt = await new jose.SignJWT(userInfo)
const jwt = await new jose.SignJWT(user)
.setProtectedHeader({ alg: 'EdDSA' })
.setExpirationTime('10 s') // 10 second JWT expiration
.sign(signingKey);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ If you have an existing OAuth server, you can integrate with Mintlify for a seam
</Step>
<Step title="Create your Info API (Optional)">
If you want to take advantage of authentication's customization features, you'll need to create an endpoint to retrieve info about your users.
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.
Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [User](../sending-data) format.

Return to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add the Info API URL
to your OAuth configuration.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs
<Step title="Create a login flow">
Create a login flow that does the following:
- Authenticate the user
- Create a JWT containing the authenticated user's info in the [UserInfo](../sending-data) format
- Create a JWT containing the authenticated user's info in the [User](../sending-data) format
- Sign the JWT with the secret key, using the EdDSA algorithm
- Create a redirect URL back to your docs, including the JWT as the hash
</Step>
Expand Down Expand Up @@ -54,7 +54,7 @@ const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');

export async function handleRequest(req: Request, res: Response) {
const userInfo = {
const user = {
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000),
groups: res.locals.user.groups,
content: {
Expand All @@ -63,7 +63,7 @@ export async function handleRequest(req: Request, res: Response) {
},
};

const jwt = await new jose.SignJWT(userInfo)
const jwt = await new jose.SignJWT(user)
.setProtectedHeader({ alg: 'EdDSA' })
.setExpirationTime('10 s')
.sign(signingKey);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ If you have an existing OAuth server that supports the PKCE flow, you can integr

<Steps>
<Step title="Create your Info API">
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.
Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [User](../sending-data) format. Take note of the scope or scopes required to access this endpoint.
</Step>
<Step title="Configure your Personalization settings">
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ This method utilizes the session authentication info already stored in your user

<Steps>
<Step title="Create your Info API">
Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [UserInfo](../sending-data) format.
Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [User](../sending-data) format.

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 `*`)
Expand Down
24 changes: 12 additions & 12 deletions settings/authentication-personalization/personalization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,36 +21,36 @@ three major features of Personalization:

### Customizing MDX Content

When writing content, you can use the `userContext` variable to access the information you have sent to your docs. Here's a simple example:
When writing content, you can use the `user` variable to access the information you have sent to your docs. Here's a simple example:

Hello, {userContext.name ?? 'reader'}!
Hello, {user.name ?? 'reader'}!

```jsx
Hello, {userContext.name ?? 'reader'}!
Hello, {user.name ?? 'reader'}!
```

This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the Personalization feature based on the customer's existing plan:

Personalization is an enterprise feature. {
userContext.org === undefined
user.org === undefined
? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
: userContext.org.plan !== 'enterprise'
? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</>
: 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>.</>
}

```jsx
Personalization is an enterprise feature. {
userContext.org === undefined
user.org === undefined
? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
: userContext.org.plan !== 'enterprise'
? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</>
: 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>.</>
}
```

<Note>
The information in `userContext` is only available after a user has logged in. For logged out users, the value of `userContext` will be `{}`. To prevent the page from crashing for logged-out users, always use optional chaining on your `userContext` fields, e.g. `{userContext.org?.plan}`
The information in `user` is only available after a user has logged in. For logged out users, the value of `user` will be `{}`. To prevent the page from crashing for logged-out users, always use optional chaining on your `user` fields, e.g. `{user.org?.plan}`
</Note>

### Prefilling API Keys
Expand All @@ -71,9 +71,9 @@ groups: ['admin']
---
```

Here's a table that displays whether a page is shown for different combinations of `groups` in UserInfo and page metadata:
Here's a table that displays whether a page is shown for different combinations of `groups` in User and page metadata:

| | `groups` not in UserInfo | `groups: []` in UserInfo | `groups: ['admin']` in UserInfo |
| | `groups` not in User | `groups: []` in User | `groups: ['admin']` in User |
| :------------------------------ | :----------------------: | :----------------------: | :-----------------------------: |
| `groups` not in metadata | ✅ | ✅ | ✅ |
| `groups: []` in metadata | ❌ | ❌ | ❌ |
Expand Down
4 changes: 2 additions & 2 deletions settings/authentication-personalization/sending-data.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: 'The shape of user data you can use to personalize your docs'
Depending on your Handshake method, your API will respond with either a raw JSON object or a signed JWT. The shape of the data is the same for both:

```tsx
type UserInfo = {
type User = {
expiresAt?: number;
groups?: string[];
content?: Record<string, any>;
Expand Down Expand Up @@ -36,7 +36,7 @@ type UserInfo = {
path="content"
type="object"
>
A bag of values that can be accessed from within MDX content using the `userContext` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {userContext.firstName}!`
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}!`
</ParamField>
<ParamField
path="apiPlaygroundInputs"
Expand Down
Loading