Publishable API Keys with Sales Channels

In this document, you’ll learn what publishable API keys are and how to use them with sales channels.

Without Publishable API Keys

When using multiple sales channels, you’ll need to specify the ID of a storefront’s sales channel. This ensures that you retrieve the products available in that sales channel and associate the sales channel with the storefront’s carts and orders.

The Store API routes accept the sales channel’s IDs differently. For example, the List Products API route accepts the sales channel’s ID as a query parameter, whereas the Create Cart API route accepts it in the request’s body.

This approach is tedious and error-prone as your storefront scales and as you develop multiple types of storefronts.

---

Introducing Publishable API Keys

The API Key module allows you to create keys for different usages. One of those usages is to create a publishable API key.

A publishable API key is a client key scoped to one or more sales channels. When passed in the header of a request, the Medusa application infers the associated sales channels.

So, instead of the previous approach of manually passing the sales channel’s ID based on the API route, you always pass the publishable API key in the header of your requests:

curl http://localhost:9000/store/products \
  x-publishable-api-key: {your_publishable_api_key}

The Medusa JS Client and Medusa React both provide the option to pass the publishable API key during initialization:

• JS Client
• Medusa React

const medusa = new Medusa({
  maxRetries: 3,
  baseUrl: "http://localhost:9000",
  publishableApiKey,
})

import { MedusaProvider } from "medusa-react"

// define query client...

const App = () => {
  return (
    <MedusaProvider
      queryClientProviderProps={{ client: queryClient }}
      baseUrl="http://localhost:9000"
      // ...
      publishableApiKey={publishableApiKey}
    >
      <MyStorefront />
    </MedusaProvider>
  )
}

Then, all requests using the client/hooks automatically include the publishable API key in the header.

---

How to Create a Publishable API Key?

To create a publishable API key, either use the Medusa Admin or the Admin API Routes.