> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kibocommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subnav Links

Subnav links allow you to embed external pages or applications directly into the Kibo Admin UI navigation. They are registered as entities in the `subnavlinks@mozu` entity list.

## Creating a Subnav Link

Make a **POST** request to the entity list endpoint:

```
POST /api/platform/entitylists/subnavlinks@mozu/entities
```

### Request Payload

```json theme={null}
{
    "path": [
        "Parent",
        "Child"
    ],
    "href": "{{your URL here}}",
    "windowTitle": "Custom Interface",
    "modalWindowTitle": "Subnav Link Title",
    "location": "ordermenu",
    "displayMode": "modal",
    "appId": "{{application ID}}",
    "badgeInitials": "CT",
    "requiredContext": "products"
}
```

### Field Descriptions

| Field              | Description                                                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`             | Array of strings defining the menu label. Use multiple elements for nested menus (e.g. `["Parent", "Child"]`).                                            |
| `href`             | The URL of your external application that will be rendered in the modal.                                                                                  |
| `windowTitle`      | Static title shown in the modal window itself.                                                                                                            |
| `modalWindowTitle` | Static title shown in the Kibo Admin sidebar menu.                                                                                                        |
| `location`         | Where in the Kibo Admin UI the link appears. See full list below.                                                                                         |
| `displayMode`      | Set to `"modal"` (static value).                                                                                                                          |
| `appId`            | The ID of an application installed on the tenant. Find it in Admin at **System > Customizations > Applications** — the app ID is visible in the page URL. |
| `badgeInitials`    | Short label/initials badge shown in the menu. Must be unique.                                                                                             |
| `requiredContext`  | *(Optional)* Context scope (e.g. `"products"`). Used for edit-page subnav links.                                                                          |

## Available `location` Values

These control where in the Admin UI the subnav link will appear:

| Value               | UI Section                                                 |
| ------------------- | ---------------------------------------------------------- |
| `productsmenu`      | Products menu                                              |
| `marketingmenu`     | Marketing menu                                             |
| `searchmenu`        | Search menu                                                |
| `contentmenu`       | Content menu                                               |
| `publishingmenu`    | Publishing menu                                            |
| `ordermenu`         | Orders menu                                                |
| `fulfiller`         | Fulfiller                                                  |
| `orderRouting`      | Order Routing                                              |
| `customermenu`      | Customers menu                                             |
| `b2baccountmenu`    | B2B Accounts menu                                          |
| `reportmenu`        | Reports menu                                               |
| `settingsmenu`      | Settings menu                                              |
| `schemamenu`        | Schema menu                                                |
| `customizationmenu` | Customizations menu                                        |
| `structuremenu`     | Structure menu                                             |
| `permissionsmenu`   | Permissions menu                                           |
| `localizationmenu`  | Localization menu                                          |
| `productsedit`      | Product edit page (requires `requiredContext: "products"`) |

**Note:** Additions to `productsmenu` require a hard refresh to display. Other locations such as `categoriesedit` or `productsedit` appear after a single refresh.

## How Requests Are Delivered to Your Application

When a user clicks a subnav link in Admin, Kibo makes a **POST** request to your configured `href` URL. The request includes:

### Query Parameters

| Param         | Description                                                         |
| ------------- | ------------------------------------------------------------------- |
| `dt`          | The date/time of the request (e.g. `Fri, 29 Nov 2024 19:49:10 GMT`) |
| `messageHash` | HMAC-SHA256 hash used to verify request authenticity                |

### POST Body (form-encoded)

| Field                  | Description                               |
| ---------------------- | ----------------------------------------- |
| `x-vol-return-url`     | The Admin URL to return to                |
| `x-vol-tenant`         | Tenant ID                                 |
| `x-vol-master-catalog` | Master Catalog ID                         |
| `x-vol-catalog`        | Catalog ID                                |
| `x-vol-site`           | Site ID                                   |
| `userId`               | ID of the Admin user who clicked the link |

## Verifying Request Authenticity

Use the `dt` and `messageHash` query parameters to confirm the request genuinely came from Kibo Admin. The following Node.js example shows the verification algorithm:

```js theme={null}
const crypto = require("crypto");

var appKey       = "YOUR.APP.KEY";
var appSecret    = "{{appSecret}}";      // From your app credentials
var receivedHash = "{{messageHash}}";    // From query param
var receivedDate = "{{dt}}";             // From query param
var rawContent   = "{{postBody}}";       // Raw POST body string

// Step 1: Concatenate the app secret with itself
var concatenated1 = appSecret + appSecret;

// Step 2: SHA-256 hash the concatenated secret, then Base64-encode it
var hash1 = crypto.createHash("sha256").update(concatenated1).digest("base64");

// Step 3: Concatenate hash1 + receivedDate + rawPostBody
var concatenated2 = hash1 + receivedDate + rawContent;

// Step 4: SHA-256 hash the second concatenation, then Base64-encode it
var generatedHash = crypto.createHash("sha256").update(concatenated2).digest("base64");

// Step 5: Compare — matching means the request is authentic
if (generatedHash === receivedHash) {
    console.log("Match! Request is authentic.");
}
```

Your `appSecret` comes from the application registered in Kibo. The `appId` in the subnav link payload must match that same application.

## Viewing and Managing Existing Subnav Links

**Via API:**

```
GET /api/platform/entitylists/subnavlinks@mozu/entities
```

**Via Admin UI:**

1. Go to **System > Schema > Custom Schema**.
2. Open Dev Tools and run: `Ext.util.Cookies.set('debugext', true)`
3. Press **Enter** and refresh the page.
4. Under **Entity Lists**, find `subnavlinks` to view or delete entries.

## Example Demos

A reference implementation (Express server + Next.js) is available at [github.com/KiboPartners/subnavlink-demos](https://github.com/KiboPartners/subnavlink-demos).