refactor(console): update M2M guide samples with real app metadata (#7818)

Author: charIeszhao

packages/console/src/assets/docs/guides/m2m-general/README.mdx

@@ -21,7 +21,7 @@ There are two common use cases of using machine-to-machine apps in Logto:
 1. **Accessing Logto Management API**: In this case, you need to assign a M2M role that include the `all` permission from the built-in Logto Management API to your M2M app.
 2. **Accessing your API resource**: In this case, you need to assign M2M roles that include permissions from your API resources to your M2M app.
 
-During the M2M app creation process, you’ll be directed to a page where you can assign machine-to-machine (M2M) roles to your applications:
+During the M2M app creation process, you'll be directed to a page where you can assign machine-to-machine (M2M) roles to your applications:
 
 <img alt="Assign M2M roles modal" src={AssignM2mRolesModalSrc} width="600px" style={{ borderRadius: '6px' }} />
 
@@ -42,104 +42,101 @@ And you also need to include your M2M app's credentials in the request header fo
 
 This is achieved by including the app's credentials in the [Basic authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization#basic_authentication) form in the request `Authorization` header, where username is the App ID, and password is the App Secret.
 
-You can find the App ID and App Secret from your M2M app's details page:
+The App ID and App Secret are as follows, and you can also find them in your M2M app details page:
 
 <ApplicationCredentials />
 
-An example of the access token request is:
+And the authentication string can be generated by encoding the app ID and app secret to Base64 format, with the fake code below:
 
-```
-POST /oidc/token HTTP/1.1
-Host: your.logto.endpoint
-Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
+<Code className="language-js">
+{`base64_encode("${props.app.id}:${props.showAppSecret ? props.secrets[0].value : '*'.repeat(props.secrets[0].value.length)}")
+// Result: ${props.showAppSecret ? btoa(`${props.app.id}:${props.secrets[0].value}`) : '*'.repeat(btoa(`${props.app.id}:${props.secrets[0].value}`).length)}`}
+</Code>
+
+An example of fetching the M2M access token request:
+
+<Code className="language-bash">
+{`POST /oidc/token HTTP/1.1
+Host: ${props.endpoint}
+Authorization: Basic ${props.showAppSecret ? btoa(`${props.app.id}:${props.secrets[0].value}`) : '*'.repeat(btoa(`${props.app.id}:${props.secrets[0].value}`).length)}
 Content-Type: application/x-www-form-urlencoded
 
 grant_type=client_credentials
-resource=https://shopping.api
-scope=read:products write:products
-```
+resource=https://${props.app.tenantId}.logto.app/api
+scope=all`}
+</Code>
 
 </Step>
 <Step title="Request an access token">
 
-<InlineNotification>
-In the following demonstration, replace `https://your.logto.endpoint` with the Logto endpoint you are targeting. For Logto Cloud, it will be `https://[your-tenant-id].logto.app`.
-</InlineNotification>
-
 <Tabs>
 
 <TabItem value="Logto Management API" label="For Logto Management API">
 
-Logto provides a built-in “Logto Management API” resource, it’s a readonly resource with the `all` permission to access Logto Management API, you can see it from your API resource list.
-The resource API indicator is in the pattern of `https://[your-tenant-id].logto.app/api` , and this will be your resource value used in the access token request body.
+Logto provides a built-in "Logto Management API" resource, it's a readonly resource with the `all` permission to access Logto Management API, you can see it from your API resource list.
+The resource API indicator is in the pattern of `https://[your-tenant-id].logto.app/api`, and this will be your resource value used in the access token request body.
 
 <img alt="Logto Management API details" src={LogtoManagementApiSrc} width="600px" style={{ borderRadius: '6px' }}/>
 
-Before accessing Logto Management API, make sure your M2M app has been assigned with M2M roles that include the `all` permission from this built-in “Logto Management API” resource.
+Before accessing Logto Management API, make sure your M2M app has been assigned with M2M roles that include the `all` permission from this built-in "Logto Management API" resource.
 
 <InlineNotification>
-Logto also provides a pre-configured “Logto Management API access” M2M role for new created tenants, which the Logto Management API resource’s all permission has already assigned to. You can use it directly without manually setting permissions. This pre-configured role can also be edited and deleted as needed.
+Logto also provides a pre-configured "Logto Management API access" M2M role for new created tenants, which the Logto Management API resource's all permission has already assigned to. You can use it directly without manually setting permissions. This pre-configured role can also be edited and deleted as needed.
 </InlineNotification>
 
 Now, compose all we have and send the request:
 
 <Tabs>
 <TabItem value="Node.js" label="Node.js">
 
-```js
-const logtoEndpoint = 'https://your.logto.endpoint'; // Replace with your Logto endpoint
-const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
-const applicationId = 'your-application-id';
-const applicationSecret = 'your-application-secret';
-const tenantId = 'your-tenant-id';
+<Code className="language-js">
+    {`const logtoEndpoint = '${props.endpoint}';
+const tokenEndpoint = '${new URL('/oidc/token', props.endpoint).href}';
+const appId = '${props.app.id}';
+const appSecret = '${props.showAppSecret ? props.secrets[0].value : '*'.repeat(props.secrets[0].value.length)}';
 
 const fetchAccessToken = async () => {
   return await fetch(tokenEndpoint, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/x-www-form-urlencoded',
-      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
-        'base64'
-      )}`,
+      Authorization: \`Basic \${Buffer.from(\`\${appId}:\${appSecret}\`).toString('base64')}\`,
+      )}\`,
     },
     body: new URLSearchParams({
       grant_type: 'client_credentials',
-      resource: `https://${tenantId}.logto.app/api`,
+      resource: 'https://${props.app.tenantId}.logto.app/api',
       scope: 'all',
     }).toString(),
   });
-};
-```
+};`}
+</Code>
 
 </TabItem>
 
 <TabItem value="cURL" label="cURL">
 
-```bash
-curl --location \
-  --request POST 'https://your.logto.endpoint' \ # Replace with your Logto endpoint
-  --header 'Authorization: Basic ${your_auth_string}' \
-  --header 'Content-Type: application/x-www-form-urlencoded' \
-  --data-urlencode 'grant_type=client_credentials' \
-  --data-urlencode 'resource=https://${tenantId}.logto.app/api' \
-  --data-urlencode 'scope=all'
-```
+<Code className="language-bash">
+{`curl --location \\
+  --request POST '${new URL('/oidc/token', props.endpoint).href}' \\
+  --header 'Authorization: Basic ${props.showAppSecret ? btoa(`${props.app.id}:${props.secrets[0].value}`) : '*'.repeat(btoa(`${props.app.id}:${props.secrets[0].value}`).length)}' \\
+  --header 'Content-Type: application/x-www-form-urlencoded' \\
+  --data-urlencode 'grant_type=client_credentials' \\
+  --data-urlencode 'resource=https://${props.app.tenantId}.logto.app/api' \\
+  --data-urlencode 'scope=all'`}
+</Code>
 
 </TabItem>
 
 </Tabs>
 
-<InlineNotification>
-For Logto Cloud users: when you’re interacting with Logto Management API, you can not use custom domain, use the default Logto endpoint `https://[your_tenant_id].logto.app/oidc/token` to grant access tokens.
-</InlineNotification>
-
 ### Access token response
 
 A successful access token response body would be like:
 
 ```json
 {
-  "access_token": "<granted-access-token>", // Use this token to access the API resource
+  "access_token": "<granted-access-token>", // E.g. eyJhb...2g
   "expires_in": 3600, // Token expiration in seconds
   "token_type": "Bearer", // Auth type for your request when using the access token
   "scope": "all" // scope `all` for Logto Management API
@@ -158,7 +155,7 @@ In your API Resource list, find the API identifier that the app needs to access.
 
 <img alt="API identifier" src={AppIdentifierSrc} width="600px" style={{ borderRadius: '6px' }} />
 
-Assume that we have `read:products` and `write:products` permissions under this “Online Shopping” API resource.
+Assume that we have `read:products` and `write:products` permissions under this "Online Shopping" API resource.
 
 Before accessing your API resource, make sure your M2M app has been assigned with M2M roles that include permissions from your API resource.
 
@@ -168,43 +165,41 @@ Now, compose all we have and send the request:
 
 <TabItem value="Node.js" label="Node.js">
 
-```js
-const logtoEndpoint = 'https://your.logto.endpoint';
-const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
-const applicationId = 'your-application-id';
-const applicationSecret = 'your-application-secret';
+<Code className="language-js">
+{`const logtoEndpoint = '${props.endpoint}';
+const tokenEndpoint = '${new URL('/oidc/token', props.endpoint).href}';
+const appId = '${props.app.id}';
+const appSecret = '${props.showAppSecret ? props.secrets[0].value : '*'.repeat(props.secrets[0].value.length)}';
 
 const fetchAccessToken = async () => {
   return await fetch(tokenEndpoint, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/x-www-form-urlencoded',
-      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
-        'base64'
-      )}`,
+      Authorization: \`Basic \${Buffer.from(\`\${appId}:\${appSecret}\`).toString('base64')}\`,
     },
     body: new URLSearchParams({
       grant_type: 'client_credentials',
       resource: 'https://shopping.api',
       scope: 'read:products write:products',
     }).toString(),
   });
-};
-```
+};`}
+</Code>
 
 </TabItem>
 
 <TabItem value="cURL" label="cURL">
 
-```bash
-curl --location \
-  --request POST 'https://your.logto.endpoint/oidc/token' \
-  --header 'Authorization: Basic ${your_auth_string}' \
-  --header 'Content-Type: application/x-www-form-urlencoded' \
-  --data-urlencode 'grant_type=client_credentials' \
-  --data-urlencode 'resource=https://shopping.api' \
-  --data-urlencode 'scope=read:products write:products'
-```
+<Code className="language-bash">
+{`curl --location \\
+  --request POST '${new URL('/oidc/token', props.endpoint).href}' \\
+  --header 'Authorization: Basic ${props.showAppSecret ? btoa(`${props.app.id}:${props.secrets[0].value}`) : '*'.repeat(btoa(`${props.app.id}:${props.secrets[0].value}`).length)}' \\
+  --header 'Content-Type: application/x-www-form-urlencoded' \\
+  --data-urlencode 'grant_type=client_credentials' \\
+  --data-urlencode 'resource=https://shopping.api' \\
+  --data-urlencode 'scope=read:products write:products'`}
+</Code>
 
 </TabItem>
 
@@ -235,34 +230,34 @@ You may notice the token response has a `token_type` field, which it's fixed to
 <Tabs>
 <TabItem value="Logto Management API" label="Interact with Logto Management API">
 
-Using the requested access token with the built-in Logto Management API resource `https://[your-tenant-id].logto.app/api` to get all applications in Logto:
+Using the requested access token with the built-in Logto Management API resource `https://[your-tenant-id].logto.app/api` to get all applications in your Logto tenant:
 
 <Tabs>
 <TabItem value="Node.js" label="Node.js">
 
-```js
-const logtoEndpoint = 'https://your.logto.endpoint'; // Replace with your Logto endpoint
-const accessToken = 'eyJhb...2g'; // Access Token
+<Code className="language-js">
+{`const logtoEndpoint = '${props.endpoint}';
+const accessToken = 'eyJhb...2g'; // Your JWT access token
 
 const fetchLogtoApplications = async () => {
-  return await fetch(`${logtoEndpoint}/api/applications`, {
+  return await fetch('${new URL('/api/applications', props.endpoint).href}', {
     method: 'GET',
     headers: {
-      Authorization: `Bearer ${accessToken}`,
+      Authorization: \`Bearer \${accessToken}\`,
     },
   });
-};
-```
+};`}
+</Code>
 
 </TabItem>
 
 <TabItem value="cURL" label="cURL">
 
-```bash
-curl --location \
-  --request GET 'https://your.logto.endpoint/api/applications' \ # Replace with your Logto endpoint
-  --header 'Authorization: Bearer eyJhbG...2g' # Access Token
-```
+<Code className="language-bash">
+{`curl --location \\
+  --request GET '${new URL('/api/applications', props.endpoint).href}' \\
+  --header 'Authorization: Bearer eyJhbG...2g' # Access Token`}
+</Code>
 
 </TabItem>
 
@@ -298,7 +293,7 @@ const fetchProducts = async () => {
 ```bash
 curl --location \
   --request GET 'https://your.api.endpoint/products' \
-  --header 'Authorization: Bearer eyJhbG...2 # Access Token
+  --header 'Authorization: Bearer eyJhbG...2 # Access token
 ```
 
 </TabItem>

packages/console/src/components/Guide/index.tsx

@@ -1,4 +1,5 @@
 import { type ApplicationResponse } from '@logto/schemas';
+import { noop } from '@silverhand/essentials';
 import classNames from 'classnames';
 import {
   type ComponentType,
@@ -32,6 +33,8 @@ export type GuideContextType = {
   redirectUris?: string[];
   postLogoutRedirectUris?: string[];
   audience?: string;
+  showAppSecret: boolean;
+  setShowAppSecret: (show: boolean) => void;
 };
 
 type Props = {
@@ -55,6 +58,8 @@ export const GuideContext = createContext<GuideContextType>({
   postLogoutRedirectUris: [],
   isCompact: false,
   audience: '',
+  showAppSecret: false,
+  setShowAppSecret: noop,
 });
 
 function Guide({ className, guideId, isEmpty, isLoading, onClose }: Props) {

packages/console/src/ds-components/CopyToClipboard/index.tsx

@@ -32,6 +32,7 @@ type Props = {
   readonly size?: 'default' | 'small';
   readonly displayType?: 'block' | 'inline';
   readonly isWordWrapAllowed?: boolean;
+  readonly onToggleVisibility?: (isVisible: boolean) => void;
 };
 
 type CopyState = TFuncKey<'translation', 'admin_console.general'>;
@@ -47,6 +48,7 @@ function CopyToClipboard(
     size = 'default',
     isWordWrapAllowed = false,
     displayType = 'inline',
+    onToggleVisibility,
   }: Props,
   ref: ForwardedRef<HTMLDivElement>
 ) {
@@ -81,6 +83,7 @@ function CopyToClipboard(
 
   const toggleHiddenContent = () => {
     setShowHiddenContent((previous) => !previous);
+    onToggleVisibility?.(!showHiddenContent);
   };
 
   return (

packages/console/src/mdx-components/ApplicationCredentials/index.tsx

@@ -9,7 +9,7 @@ import TextLink from '@/ds-components/TextLink';
 import styles from './index.module.scss';
 
 function ApplicationCredentials() {
-  const { app, secrets } = useContext(GuideContext);
+  const { app, secrets, setShowAppSecret } = useContext(GuideContext);
   const { id } = app ?? {};
   const { t } = useTranslation(undefined, { keyPrefix: 'admin_console' });
 
@@ -44,6 +44,7 @@ function ApplicationCredentials() {
             displayType="block"
             value={secrets[0].value}
             variant="border"
+            onToggleVisibility={setShowAppSecret}
           />
         </FormField>
       )}

packages/console/src/pages/ApiResourceDetails/components/ApiGuide/index.tsx

@@ -1,6 +1,6 @@
 import { type Resource } from '@logto/schemas';
 import { conditional } from '@silverhand/essentials';
-import { useContext, useMemo } from 'react';
+import { useContext, useMemo, useState } from 'react';
 
 import { guides } from '@/assets/docs/guides';
 import Guide, { GuideContext, type GuideContextType } from '@/components/Guide';
@@ -16,6 +16,7 @@ type Props = {
 
 function ApiGuide({ className, guideId, apiResource, isCompact, onClose }: Props) {
   const { tenantEndpoint } = useContext(AppDataContext);
+  const [showAppSecret, setShowAppSecret] = useState(false);
 
   const guide = guides.find(({ id }) => id === guideId);
 
@@ -29,9 +30,11 @@ function ApiGuide({ className, guideId, apiResource, isCompact, onClose }: Props
             isCompact: Boolean(isCompact),
             endpoint: tenantEndpoint?.href ?? '',
             audience: apiResource.indicator,
+            showAppSecret,
+            setShowAppSecret,
           }
       ) satisfies GuideContextType | undefined,
-    [apiResource, guide, isCompact, tenantEndpoint?.href]
+    [apiResource, guide, isCompact, showAppSecret, tenantEndpoint?.href]
   );
 
   return memorizedContext ? (