From f906c45f6b6ebc277b00ca10b3234a4d120ef6b7 Mon Sep 17 00:00:00 2001 From: Han Wang <44352119+handotdev@users.noreply.github.com> Date: Fri, 27 Dec 2024 23:53:33 -0800 Subject: [PATCH] Replace userContext with User --- .../authentication-setup/jwt.mdx | 6 ++--- .../authentication-setup/oauth.mdx | 2 +- .../personalization-setup/jwt.mdx | 6 ++--- .../personalization-setup/oauth.mdx | 2 +- .../personalization-setup/shared-session.mdx | 2 +- .../personalization.mdx | 24 +++++++++---------- .../sending-data.mdx | 4 ++-- 7 files changed, 23 insertions(+), 23 deletions(-) diff --git a/settings/authentication-personalization/authentication-setup/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx index 16d6f59eb..d35fd7e3a 100644 --- a/settings/authentication-personalization/authentication-setup/jwt.mdx +++ b/settings/authentication-personalization/authentication-setup/jwt.mdx @@ -18,7 +18,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs 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 @@ -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: { @@ -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); diff --git a/settings/authentication-personalization/authentication-setup/oauth.mdx b/settings/authentication-personalization/authentication-setup/oauth.mdx index bd90afae4..45206968c 100644 --- a/settings/authentication-personalization/authentication-setup/oauth.mdx +++ b/settings/authentication-personalization/authentication-setup/oauth.mdx @@ -26,7 +26,7 @@ If you have an existing OAuth server, you can integrate with Mintlify for a seam 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. diff --git a/settings/authentication-personalization/personalization-setup/jwt.mdx b/settings/authentication-personalization/personalization-setup/jwt.mdx index 7d2b4470e..3e4fe195a 100644 --- a/settings/authentication-personalization/personalization-setup/jwt.mdx +++ b/settings/authentication-personalization/personalization-setup/jwt.mdx @@ -19,7 +19,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs 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 @@ -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: { @@ -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); diff --git a/settings/authentication-personalization/personalization-setup/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx index b90859f9b..d786a042f 100644 --- a/settings/authentication-personalization/personalization-setup/oauth.mdx +++ b/settings/authentication-personalization/personalization-setup/oauth.mdx @@ -13,7 +13,7 @@ If you have an existing OAuth server that supports the PKCE flow, you can integr - 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. Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields: diff --git a/settings/authentication-personalization/personalization-setup/shared-session.mdx b/settings/authentication-personalization/personalization-setup/shared-session.mdx index a73aa0a83..5066952c1 100644 --- a/settings/authentication-personalization/personalization-setup/shared-session.mdx +++ b/settings/authentication-personalization/personalization-setup/shared-session.mdx @@ -13,7 +13,7 @@ This method utilizes the session authentication info already stored in your user - 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 `*`) diff --git a/settings/authentication-personalization/personalization.mdx b/settings/authentication-personalization/personalization.mdx index 37c4af910..cf9942755 100644 --- a/settings/authentication-personalization/personalization.mdx +++ b/settings/authentication-personalization/personalization.mdx @@ -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 Mintlify dashboard. -: userContext.org.plan !== 'enterprise' - ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. +: 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. } ```jsx Personalization is an enterprise feature. { - userContext.org === undefined + user.org === undefined ? <>To access this feature, first create an account at the Mintlify dashboard. - : userContext.org.plan !== 'enterprise' - ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. + : 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. } ``` - 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}` ### Prefilling API Keys @@ -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 | ❌ | ❌ | ❌ | diff --git a/settings/authentication-personalization/sending-data.mdx b/settings/authentication-personalization/sending-data.mdx index bb7b17d17..e969fa8bc 100644 --- a/settings/authentication-personalization/sending-data.mdx +++ b/settings/authentication-personalization/sending-data.mdx @@ -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; @@ -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}!`