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.