Use a Publishable API Key in the Storefront

In this guide, you'll learn how to create and use the publishable API key in your storefront to interact with the Medusa application's Store API routes.

What is a Publishable API Key?#

When sending requests to the /store API routes, you must pass a publishable API key in the header of your request.

Publishable API keys specify the scope of a request. Admin users create them, and they can only be used on the client-side, such as in a storefront.

Publishable API keys are associated with sales channels. Then, when the publishable API key is passed in the header of a request, the Medusa application automatically infers what sales channel is being used.

How to Create a Publishable API Key?#

You create a publishable API key either using the Medusa Admin or the Admin API routes.

For example, using the Create API Key API Route:

Code
1curl -X POST 'http://localhost:9000/admin/api-keys' \2-H 'Authorization: Bearer {token}' \3-H 'Content-Type: application/json' \4--data-raw '{5  "title": "Storefront Key",6  "type": "publishable"7}'

Tip: Learn how to send authenticated admin requests in the Admin API reference

Add Sales Channels to the Publishable API Key's Scope#

To add sales channels to the publishable API key's scope, you can either use the Medusa Admin, or send a request to the Manage Sales Channels API route:

Code
1curl -X POST 'http://localhost:9000/admin/api-keys/apk_123/sales-channels' \2-H 'Authorization: Bearer {token}' \3-H 'Content-Type: application/json' \4--data-raw '{5  "add": ["sc_123"]6}'

Make sure to replace apk_123 with the ID of the publishable API key, and sc_123 with the ID of the sales channel.

How to Use Publishable API Key in Storefront Requests#

In your storefront, pass the x-publishable-api-key in the header of all your requests to the Medusa application.

When using the JS SDK, set the publishable API key as an environment variable and pass it to the JS SDK's configurations.

For example:

Code
1import Medusa from "@medusajs/js-sdk"2
3let MEDUSA_BACKEND_URL = "http://localhost:9000"4
5if (process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL) {6  MEDUSA_BACKEND_URL = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL7}8
9export const sdk = new Medusa({10  baseUrl: MEDUSA_BACKEND_URL,11  debug: process.env.NODE_ENV === "development",12  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,13})

Where NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY is an environment variable that holds your publishable API key's token.

The JS SDK will now take care of passing the publishable API key in the header of all requests to the Medusa application.

Was this page helpful?