Skip to main content
Connecting Medusa to Vortex IQ gives the AI OS a live read on your Medusa data, feeding the Nerve Centre dashboard, Vortex Mind diagnostics, and Ask Viq.

​
What data Vortex IQ reads from Medusa

  • Product
  • ProductVariant
  • Order
  • Customer
  • Region

​
How to connect

Medusa uses credential-based authentication rather than OAuth. You provide these values directly rather than approving a redirect.
1

Open Connected Sources

In your Vortex IQ workspace, go to Settings → Connected Sources. You need Admin role in the workspace to connect sources.
2

Find the Medusa card

Locate the Medusa connector card and click + Connect. The connector drawer opens with a credential form.
3

Gather your credentials from Medusa

You will need:
  • Medusa Backend URL: Per-merchant Medusa backend base URL where the Admin API lives, e.g. https://commerce.yourbrand.com. Admin API path /admin is appended automatically.
  • Admin API Token: Admin API token from the Medusa admin dashboard (Settings → API key management → Secret keys), or a JWT from /auth/user/emailpass. Sent as Authorization: Bearer.
  • Publishable API Key: Optional pk_… key scoping which sales channels are visible. Only needed when the merchant restricts admin reads by sales channel.
4

Enter credentials in Vortex IQ

Paste each value into its matching field in the connector drawer.
5

Verify and connect

Click Verify and Connect. Vortex IQ makes a test API call to validate the credentials before saving them.
Vortex IQ only ever requests read-only access. Where Medusa offers scoped or read-only API keys, use one.

​
Available KPI cards

Vortex IQ populates 29 Nerve Centre cards from your Medusa data. See the Medusa KPI card reference for the full list with definitions, calculations, and sentiment bands.

​
Troubleshooting

Re-check each value against the Medusa developer console for typos or trailing whitespace. If a scope or permission is missing, Medusa will typically return a 401 or 403 on the verification call rather than a generic failure.
Allow time for the first sync to complete; large accounts can take longer. If cards are still empty after an hour, disconnect and reconnect to confirm the credentials were saved correctly.