Using the publishable key
Every Storefront API request carries your store’s publishable key. This page shows where the key comes from, how the SDK and the kit send it, which browser origins it accepts and what to do when you roll it. For the difference between a publishable key and a secret key, see the authentication guide.
Where the key comes from
Section titled “Where the key comes from”The store owner copies it from Settings › API Keys, on the Storefront publishable key card. There is one key for each store. The key is meant to ship in a storefront, because it can only read the catalog and act as a shopper. For the steps, see Create and manage API keys.
In the kit’s single mode, put the key in ECOMWEB_PUBLISHABLE_KEY and copy it to NEXT_PUBLIC_ECOMWEB_PUBLISHABLE_KEY in next.config.mjs, as in the quickstart. publicConfig reads it for browser code, and serverConfig reads it for server code. When the key is missing, the first request fails with an error that names ECOMWEB_PUBLISHABLE_KEY.
import { publicConfig } from "@ecomweb/storefront-kit/config";
const { storefrontApiKey, storeRef } = publicConfig();How the SDK sends it
Section titled “How the SDK sends it”The SDK never sets the key itself. The HTTP client you give createEcomwebSdk owns the x-storefront-api-key header, and the SDK only adds X-Ecomweb-Client with its version. The kit’s clients set the header for you in three places.
| Caller | How the key is sent |
|---|---|
| Browser, public calls | The kit’s publicApiClient adds x-storefront-api-key to each request to the API |
| Browser, signed-in calls | The browser calls your own /api/backend route. The proxy adds the key and the shopper’s token on the server, so the browser sends neither |
| Server | Auth routes and the middleware’s session refresh add the key from serverConfig |
// The header the API reads. The kit adds it, you do not.// x-storefront-api-key: <publishable key>If you write your own HTTP client, add the header to every request, as shown in Install and configure. The API also accepts the key as Authorization: Bearer <key>, but a Bearer value shaped like a session token is never read as a key, so use x-storefront-api-key.
A request with no key gets 401 API key required in x-storefront-api-key header. A key the API does not know gets 401 Invalid API key. The SDK throws both as an ApiClientError. See Errors in the SDK.
Allowed sites and previews
Section titled “Allowed sites and previews”The API compares the Origin header of a browser request with the key’s allowed sites and answers 403 Origin not allowed for this API key when it is not listed. EcomWeb keeps the list for you. It holds your store’s address, your custom domain, localhost and 127.0.0.1 on any port, and the sites of themes you connect from your own server. The list is never empty, so localhost is always allowed.
A request with no Origin header skips the check. That is what server-side code sends, including the kit’s route handlers and server components. Hosted preview sites of your own store, such as https://p-<slug>.<preview domain>, are accepted for your key even though they are not on the list.
To use the key from a site that is not on the list, connect the site as a self-hosted theme. See Connect a self-hosted site.
Rolling the key
Section titled “Rolling the key”The store owner can roll the key from the same card. The old key keeps working for 7 more days. During that time, update ECOMWEB_PUBLISHABLE_KEY and rebuild, because Next.js inlines the NEXT_PUBLIC_ value at build time. After the 7 days the old key answers 401 API key is inactive, revoked, or expired. The kit does not read the key again at runtime in the browser, so a deployed storefront keeps the old key until you deploy again.
Key methods
Section titled “Key methods”| Method | What it does |
|---|---|
publicConfig |
Reads the key and other public settings for browser code |
parsePublicConfig |
Parses a set of variables you pass in, such as in a test |
serverConfig |
Reads the key and other settings for server code |
publicApiClient |
The kit’s browser client that sends the key |
createEcomwebSdk |
Builds the SDK from clients that send the key |
withClientHeader |
Wraps your own client so each request carries the SDK version |