Skip to content

Authentication

Every request to the EcomWeb API carries an API key. This guide shows which key to use, which header carries it, and what the API checks before it lets a request through. You need a key first. To create one, see Create and manage API keys.

The base URL for all examples is https://apibase.ecomweb.app/api/v1.

Secret key Publishable key
Use it in Servers, scripts and CI Storefront code, including code that runs in the browser
Header x-api-key x-storefront-api-key
Reaches The Store API, limited by the key’s scopes The Storefront API only, with shopper-level access
How many As many as you create One per store
Safe to expose No Yes, it is meant to ship in a storefront

A key belongs to one store and only works for that store.

Put the key in the x-api-key header.

Terminal window
curl "https://apibase.ecomweb.app/api/v1/stores/<store ref>/products" \
-H "x-api-key: <secret key>"

The API also accepts the key as Authorization: Bearer <secret key>. When a request carries both headers, x-api-key is read first. A Bearer value that is 100 characters or longer is treated as a signed-in user’s session token, not as a key, so use x-api-key when you can.

Put the key in the x-storefront-api-key header.

Terminal window
curl "https://apibase.ecomweb.app/api/v1/public/stores/<store ref>/products" \
-H "x-storefront-api-key: <publishable key>"

Authorization: Bearer <publishable key> also works, and x-storefront-api-key wins when both are present. A Bearer value that looks like a session token (three parts separated by dots) is never read as a key, because shoppers send their access token that way.

A publishable key only accepts browser requests from the sites on its allowed list. EcomWeb keeps the list for you: your store’s address, your custom domain, http://localhost and http://127.0.0.1 on any port (the http forms only, not https), and the sites of themes you connect from your own server. The API compares the request’s Origin header with that list and answers 403 Origin not allowed for this API key when it does not match. A request with no Origin header, which is what a server sends, skips this check.

A publishable key cannot call the Store API. It gets a 403 there, whatever its scopes.

A secret key can only use the scopes you gave it, such as read:products. A read-only key can only hold read scopes. For the full list and which operations need which scope, see the scopes guide.

A key stops working when any of these is true:

  • It has passed its expiry date.
  • It is paused, which means Active is off.
  • It is revoked.
  • It is a publishable key you rolled, and the 7 days of overlap are over.

The API answers all four the same way: 401 API key is inactive, revoked, or expired. A key it has never seen gets 401 Invalid API key.

Keys are also tied to the person who created them. When that person leaves the store, is removed, is demoted, or hands over ownership, EcomWeb revokes the keys they created. Only a store owner can hold secret keys. As a second check, the API refuses a secret key whose creator no longer qualifies, even if the revoke has not run yet. That request gets 401 API key is no longer valid: the member who created it no longer has permission to manage API keys for this store. After an ownership transfer, the new owner creates new keys.

A key can carry an IP allow list, set in the IP Whitelist field when you create or edit it in Settings › API Keys. Each entry is one address, such as 203.0.113.7, or a range in CIDR form, such as 10.0.0.0/24. IPv4 and IPv6 both work. An empty list allows any address.

The API checks the address that opens the connection to EcomWeb. It ignores X-Forwarded-For and X-Real-IP, so a caller cannot claim another address. A request from an address outside the list gets 403 IP address not whitelisted for this API key. If your server reaches the internet through a proxy or a NAT, list the proxy’s public address.

If a secret key is used on a Storefront API route, the dashboard marks it with a Storefront use badge in Settings › API Keys. The badge means the key is probably shipped in a storefront. Anyone who opens the site can read a key that ships in a browser, so switch that code to the publishable key and then revoke the secret key.

Status Message Cause
401 Authentication required: provide JWT in Authorization header or API key in x-api-key header A Store API request with no key
401 API key required in x-storefront-api-key header A Storefront API request with no key
401 Invalid API key The key does not exist
401 API key is inactive, revoked, or expired The key is paused, revoked or past its expiry, or a rolled publishable key has retired
401 API key is no longer valid: the member who created it ... The key’s creator no longer holds the right to manage keys
403 Insufficient API key scopes. Required: ... The key lacks a scope the operation needs
403 A readonly API key cannot perform this action. Required: ... A read-only key on an operation that is not a read
403 Publishable keys can only call storefront (public) endpoints A publishable key on a Store API route
403 IP address not whitelisted for this API key The caller’s address is not on the key’s IP allow list
403 Origin not allowed for this API key A browser request from a site that is not on the key’s allowed list
403 API key does not have access to this store A Storefront API request with a key that belongs to a different store than the one in the URL

Use the status to decide what to do and the message to find the cause. For the other error bodies and a retry guide, see the errors guide.