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.
Two kinds of key
Section titled “Two kinds of key”| 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.
Send a secret key
Section titled “Send a secret key”Put the key in the x-api-key header.
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.
Send a publishable key
Section titled “Send a publishable key”Put the key in the x-storefront-api-key header.
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.
Scopes
Section titled “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.
Expiry, pausing and revocation
Section titled “Expiry, pausing and revocation”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.
IP allow list
Section titled “IP allow list”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.
The “Storefront use” label
Section titled “The “Storefront use” label”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.
Errors you will see
Section titled “Errors you will see”| 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.