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.

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.

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.

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.

This key is optional. If you are unsure whether you need it, you can skip this step and add it later.

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

If you need help configuring webhooks, contact Violet support or refer to the Medusa Subscribers documentation.

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.