docs: general updates to documentation pages (#13128)

2025-08-01 18:59:46 +03:00
1 parent 522fc12d7a
commit 89886ba518
@@ -10,6 +10,8 @@ export const metadata = {

 # {metadata.title}

+In this guide, you'll learn how to add an action menu to your Medusa Admin customizations.
+
 The Medusa Admin often provides additional actions in a dropdown shown when users click a three-dot icon.

 ![Example of an action menu in the Medusa Admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1728291319/Medusa%20Resources/action-menu_jnus6k.png)
@@ -8,6 +8,8 @@ export const metadata = {

 # {metadata.title}

+In this guide, you'll learn how to create a container component that matches the Medusa Admin's design conventions.
+
 The Medusa Admin wraps each section of a page in a container.

 ![Example of a container in the Medusa Admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1728287102/Medusa%20Resources/container_soenir.png)
@@ -8,6 +8,8 @@ export const metadata = {

 # {metadata.title}

+In this guide, you'll learn how to create forms that match the Medusa Admin's design conventions.
+
 The Medusa Admin has two types of forms:

 1. Create forms, created using the [FocusModal UI component](!ui!/components/focus-modal).
@@ -59,7 +61,7 @@ export const CreateForm = () => {
  })

  const handleSubmit = form.handleSubmit(({ name }) => {
-    // TODO submit to backend
+    // TODO: submit to backend
    console.log(name)
  })

@@ -127,7 +129,7 @@ export const CreateForm = () => {

 Unlike other components in this documentation, this form component isn't reusable. You have to create one for every resource that has a create form in the admin.

-Start by creating the file `src/admin/components/create-form.tsx` that you'll create the form in.
+Start by creating the file `src/admin/components/create-form.tsx` in which you'll create the form.

 ### Create Validation Schema

@@ -163,7 +165,7 @@ export const CreateForm = () => {
  })

  const handleSubmit = form.handleSubmit(({ name }) => {
-    // TODO submit to backend
+    // TODO: submit to backend
    console.log(name)
  })

@@ -344,7 +346,7 @@ export const EditForm = () => {
  })

  const handleSubmit = form.handleSubmit(({ name }) => {
-    // TODO submit to backend
+    // TODO: submit to backend
    console.log(name)
  })

@@ -406,7 +408,7 @@ export const EditForm = () => {

 Unlike other components in this documentation, this form component isn't reusable. You have to create one for every resource that has an edit form in the admin.

-Start by creating the file `src/admin/components/edit-form.tsx` that you'll create the form in.
+Start by creating the file `src/admin/components/edit-form.tsx` in which you'll create the form.

 ### Create Validation Schema

@@ -442,7 +444,7 @@ export const EditForm = () => {
  })

  const handleSubmit = form.handleSubmit(({ name }) => {
-    // TODO submit to backend
+    // TODO: submit to backend
    console.log(name)
  })

@@ -10,6 +10,8 @@ export const metadata = {

 # {metadata.title}

+In this guide, you'll learn how to create a header component that matches the Medusa Admin's design conventions.
+
 Each section in the Medusa Admin has a header with a title, and optionally a subtitle with buttons to perform an action.

 ![Example of a header in a section](https://res.cloudinary.com/dza7lstvk/image/upload/v1728288562/Medusa%20Resources/header_dtz4gl.png)
@@ -10,6 +10,8 @@ export const metadata = {

 # {metadata.title}

+In this guide, you'll learn how to create a JSON view section that matches the Medusa Admin's design conventions.
+
 Detail pages in the Medusa Admin show a JSON section to view the current page's details in JSON format.

 ![Example of a JSON section in the admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1728295129/Medusa%20Resources/json_dtbsgm.png)
@@ -10,6 +10,8 @@ export const metadata = {

 # {metadata.title}

+In this guide, you'll learn how to create a section row component that matches the Medusa Admin's design conventions.
+
 The Medusa Admin often shows information in rows of label-values, such as when showing a product's details.

 ![Example of a section row in the Medusa Admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1728292781/Medusa%20Resources/section-row_kknbnw.png)
@@ -8,6 +8,8 @@ export const metadata = {

 # {metadata.title}

+In this guide, you'll learn how to create a layout component that matches the Medusa Admin's design conventions for pages with a single column of content.
+
 The Medusa Admin has pages with a single column of content.

 <Note>
@@ -8,6 +8,8 @@ export const metadata = {

 # {metadata.title}

+In this guide, you'll learn how to create a layout component that matches the Medusa Admin's design conventions for pages with two columns of content.
+
 The Medusa Admin has pages with two columns of content.

 <Note>
@@ -4,22 +4,51 @@ export const metadata = {

 # {metadata.title}

-In this document, you’ll learn about the different types of API keys, their expiration and verification.
+In this guide, you’ll learn about the different types of API keys, their expiration and verification.

 ## API Key Types

 There are two types of API keys:

 - `publishable`: A public key used in client applications, such as a storefront.
+    - This API key is useful for operations that do not require authentication, such as fetching product data or categories.
 - `secret`: A secret key used for authentication and verification purposes, such as an admin user’s authentication token or a password reset token.
+    - This API key is useful for operations that require authentication, such as creating orders or managing products as an admin user.

 The API key’s type is stored in the `type` property of the [ApiKey data model](/references/api-key/models/ApiKey).

+### Default Scopes and Permissions
+
+In your Medusa application, a `publishable` API key is only useful to send requests to the [Store API routes](!api!/store). Learn more about it in the [Publishable API Keys](../../sales-channel/publishable-api-keys/page.mdx) guide.
+
+In addition, a `secret` API key allows you to access the [Admin API routes](!api!/admin) and perform actions as the admin user that the key was created for. The `created_by` property of the [ApiKey data model](/references/api-key/models/ApiKey) indicates the ID of the associated admin user.
+
+---
+
+## API Key Creation
+
+When using the [Medusa Admin](!user-guide!/settings/developer) or [API routes](!api!/admin#api-keys), only admin users can create API keys. 
+
+You can also create API keys in your customizations using the [createApiKeysWorkflow](/references/medusa-workflows/createApiKeysWorkflow).
+
+---
+
+## API Key Tokens
+
+The API key data model has a `token` property that contains the actual key used for authentication.
+
+This token is created using the `salt` property in the data model, which is a random string generated when the API key is created. The salt is a `64`-character hexadecimal string generated randomly using the `crypto` module in Node.js.
+
+For display purposes, the API key data model also has a `redacted` property that contains the first six characters of the token, followed by `...`, then the last three characters of the token. You can use this property to show the API key in the UI without revealing the full token.
+
 ---

 ## API Key Expiration

-An API key expires when it’s revoked using the [revoke method of the module’s main service](/references/api-key/revoke).
+An API key expires when it’s revoked using the [revokeApiKeysWorkflow](/references/medusa-workflows/revokeApiKeysWorkflow). This method will set the following properties in the API key:
+
+- `revoked_at`: The date and time when the API key was revoked.
+- `revoked_by`: The ID of the user who revoked the API key.

 The associated token is no longer usable or verifiable.

@@ -197,7 +197,7 @@ export const generatedEditDates = {
  "app/infrastructure-modules/page.mdx": "2025-05-21T13:01:59.821Z",
  "app/infrastructure-modules/workflow-engine/redis/page.mdx": "2025-06-24T08:50:10.115Z",
  "app/infrastructure-modules/notification/sendgrid/page.mdx": "2025-05-20T07:51:40.715Z",
-  "app/commerce-modules/api-key/concepts/page.mdx": "2024-10-07T13:59:37.529Z",
+  "app/commerce-modules/api-key/concepts/page.mdx": "2025-08-01T15:40:51.530Z",
  "app/infrastructure-modules/workflow-engine/page.mdx": "2025-04-17T08:29:00.881Z",
  "app/infrastructure-modules/cache/page.mdx": "2025-04-17T08:29:00.741Z",
  "app/infrastructure-modules/file/s3/page.mdx": "2025-06-24T08:50:10.115Z",
@@ -2088,16 +2088,16 @@ export const generatedEditDates = {
  "references/user/interfaces/user.IModuleService/page.mdx": "2024-12-09T13:22:04.708Z",
  "references/user/interfaces/user.MessageAggregatorFormat/page.mdx": "2024-12-09T13:22:04.712Z",
  "app/troubleshooting/dist-imports/page.mdx": "2024-10-03T09:19:37.639Z",
-  "app/admin-components/components/action-menu/page.mdx": "2024-10-07T11:16:26.178Z",
-  "app/admin-components/components/container/page.mdx": "2024-10-07T11:15:58.824Z",
-  "app/admin-components/components/header/page.mdx": "2024-10-07T11:16:47.407Z",
-  "app/admin-components/components/json-view-section/page.mdx": "2024-10-07T11:15:58.833Z",
-  "app/admin-components/components/section-row/page.mdx": "2024-10-07T11:15:58.832Z",
+  "app/admin-components/components/action-menu/page.mdx": "2025-08-01T15:09:35.277Z",
+  "app/admin-components/components/container/page.mdx": "2025-08-01T15:10:35.250Z",
+  "app/admin-components/components/header/page.mdx": "2025-08-01T15:16:34.931Z",
+  "app/admin-components/components/json-view-section/page.mdx": "2025-08-01T15:16:57.661Z",
+  "app/admin-components/components/section-row/page.mdx": "2025-08-01T15:17:24.464Z",
  "app/admin-components/components/table/page.mdx": "2025-03-03T14:53:37.952Z",
  "app/admin-components/page.mdx": "2025-03-10T10:42:41.345Z",
-  "app/admin-components/layouts/single-column/page.mdx": "2024-10-07T11:16:06.435Z",
-  "app/admin-components/layouts/two-column/page.mdx": "2024-10-07T11:16:10.092Z",
-  "app/admin-components/components/forms/page.mdx": "2024-10-09T12:48:04.229Z",
+  "app/admin-components/layouts/single-column/page.mdx": "2025-08-01T15:17:42.109Z",
+  "app/admin-components/layouts/two-column/page.mdx": "2025-08-01T15:18:00.109Z",
+  "app/admin-components/components/forms/page.mdx": "2025-08-01T15:18:59.686Z",
  "app/commerce-modules/auth/reset-password/page.mdx": "2025-08-01T12:07:32.023Z",
  "app/storefront-development/customers/reset-password/page.mdx": "2025-03-27T14:46:51.424Z",
  "app/commerce-modules/api-key/links-to-other-modules/page.mdx": "2025-04-17T15:39:39.374Z",