> For the complete documentation index, see [llms.txt](https://merchant-help.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://merchant-help.violet.io/platform-guides/medusa.md).

# Medusa

This guide is intended for Medusa v2 merchants who are connecting their self-hosted Medusa store to Violet. During this process, the merchant will create a Secret API Key in the Medusa admin dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created credentials and can revoke them at any time from within their Medusa admin dashboard. *Total time for completion is around 5 minutes.*

## Step 1: Creating the Admin API Token (Secret API Key)

The Admin API Token is **required** to connect your Medusa store to Violet. It allows Violet to sync your products, manage orders, and access store information on your behalf.

1. Log in to your Medusa admin dashboard.
2. Navigate to **Settings > Secret API Keys**.
3. Click **"Create Secret API Key"**.
4. Enter a title for the key (e.g., "Violet Integration").
5. Click **Create** and copy the generated secret key.

{% hint style="warning" %}
**Important:** The full secret key is only displayed once at creation time. Copy and save it securely before closing the dialog. If you lose the key, you will need to create a new one.
{% endhint %}

{% hint style="info" %}
Medusa Secret API Keys provide full admin access and are not granularly scoped. Violet uses this key for product synchronization (`read_products`), order management (`read_orders`, `write_orders`), and store profile access.
{% endhint %}

## Step 2: Locating the Store Publishable API Key (Optional)

The Store Publishable API Key enables an optimized cart-based checkout flow through Medusa's storefront API, including real-time cart calculations with shipping rates and tax. If not provided, Violet will use an alternative order creation method.

1. In your Medusa admin dashboard, navigate to **Settings > API Key Management** (or **Settings > Publishable API Keys**, depending on your Medusa version).
2. Locate or create a publishable API key for your storefront.
3. Copy the publishable key and keep it available for Step 4.

{% hint style="info" %}
This key is optional. If you are unsure whether you need it, you can skip this step and add it later.
{% endhint %}

## Step 3: Configuring Webhooks (Optional)

Webhooks allow your Medusa store to notify Violet of product and order changes in real time. Without webhooks, Violet will still synchronize data, but changes may not appear immediately.

Medusa v2 does not provide a built-in admin UI for webhook configuration. Webhooks are configured server-side using a subscriber or notification module in your Medusa project.

1. In your Medusa project codebase, create or update a subscriber that sends HTTP POST requests to the Violet webhook endpoint:

   ```
   https://api.violet.io/v1/sync/external/events/medusa?merchant_id={YOUR_MERCHANT_ID}
   ```

   Your `merchant_id` will be provided after you complete the connection in Step 4.
2. Configure the subscriber to send the following event types:
   * `product.created`
   * `product.updated`
   * `product.deleted`
   * `order.placed`
   * `order.updated`
   * `order.canceled`
3. Include the following headers in each webhook request:
   * `x-medusa-event`: The event name (e.g., `product.updated`)
   * `x-medusa-signature`: HMAC-SHA256 signature of the request body using a shared secret

{% hint style="info" %}
If you need help configuring webhooks, contact Violet support or refer to the [Medusa Subscribers documentation](https://docs.medusajs.com/resources/references/medusa-workflows/subscribers).
{% endhint %}

## Step 4: Provide Credentials to Violet

Once you have your credentials, return to the Violet Connect onboarding tool and enter the following:

1. When prompted for your store URL, enter the full URL of your Medusa server including the protocol (e.g., `https://store.example.com`). Do not include a trailing slash.
2. Enter your **Admin API Token** (Secret API Key) obtained in Step 1 in the "Admin API Token" field.
3. *(Optional)* Enter your **Store Publishable Key** obtained in Step 2 in the "Store Publishable Key" field.

Once entered, click the **Connect** button to validate the credentials and complete the connection between your store and Violet. Violet will verify your Admin API Token by connecting to your Medusa server — if the token is invalid or the server cannot be reached, you will receive an error message.

If the credentials are invalid, check for:

* Spaces or other copy/paste errors in the API token
* The store URL is correct and accessible from the internet
* The Secret API Key has not been revoked

Upon success you will be redirected back to the channel who first sent you to Violet.

***

### Credential Summary

| Credential                       | Required | Where to Find                                                     |
| -------------------------------- | -------- | ----------------------------------------------------------------- |
| Store URL                        | Yes      | Your Medusa server's base URL (e.g., `https://store.example.com`) |
| Admin API Token (Secret API Key) | Yes      | Medusa admin > Settings > Secret API Keys > Create Secret API Key |
| Store Publishable Key            | No       | Medusa admin > Settings > API Key Management (Publishable)        |

***

### Special Considerations

#### Self-Hosted Platform

Unlike SaaS platforms, Medusa is self-hosted. This means:

* Your store URL is unique to your deployment — there is no standard domain like `.myshopify.com`
* Your Medusa server must be accessible from the internet for Violet to connect
* Ensure your server's firewall or reverse proxy allows inbound connections from Violet's IP ranges

#### Secret API Key Security

Medusa Secret API Keys provide full admin access and do not expire. Treat them like passwords:

* Do not share them in plain text over email or chat
* If you suspect a key has been compromised, revoke it immediately in **Settings > Secret API Keys** and create a new one
* Creating a new key and updating it in Violet Connect will restore the connection

#### Revoking Credentials

You can revoke your Secret API Key at any time by navigating to **Settings > Secret API Keys** in your Medusa admin dashboard and deleting the key. This will immediately disconnect your store from Violet until a new key is provided.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://merchant-help.violet.io/platform-guides/medusa.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.