Skip to content

Create and manage API keys

An API key lets a server, an automation tool or CI read and write your store’s data without anyone signing in. You choose which scopes the key can use and when it expires, and you can revoke it at any time. A key only works for the store that created it.

There are two kinds. A secret key is for code that runs on a server, and it is sent in the x-api-key header. A publishable key is for storefront code that runs in the browser, and it can only do what a shopper can do. It is sent in the x-storefront-api-key header. For how requests are authenticated, see the authentication guide.

  1. Go to Settings › API Keys and click Create API Key.
  2. Enter a Key Name, for example the name of the system that will use the key.
  3. Under Key Type, keep Standard, or choose Read only if the system only needs to read data. A read-only key can only have read scopes.
  4. Under Scopes, check each scope the key needs, for example read:products. Checking a group name such as read or write selects the whole group.
  5. Check the Expires At date. A new key expires after 90 days. You can pick another date, or clear the date for a key that must never expire.
  6. Click Create.
  7. In the API Key Created box, click Copy and paste the key into your system’s secret storage, for example a server or CI environment variable.
  8. Click I’ve saved this key.

Under IP Whitelist, enter one IP address and press Enter. Repeat for each address. Both IPv4 and IPv6 addresses work, and so do CIDR ranges such as 10.0.0.0/24. If you leave the list empty, the key accepts requests from any address.

Send the key in the x-api-key header. The key only works for the scopes you chose.

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

The store ref is the part after /store/ in the dashboard’s address bar. With the EcomWeb CLI, put the key in the ECOMWEB_API_KEY variable. The key takes priority over a signed-in session, and the CLI does not write it to disk.

Terminal window
# Read the product list with an API key, for example in CI
ECOMWEB_API_KEY=<secret key> ecomweb products list --store-ref <store ref>
  1. Go to Settings › API Keys.
  2. On the key’s row, open More actions and select Edit.
  3. Change the name, scopes, IP list or expiry date.
  4. To pause the key, turn off Active.
  5. Click Save Changes.

You cannot change the key type after you create the key. To use a different type, create a new key. The Last Used and Requests columns show which keys are still in use. The Revoked and expired view lists keys that no longer work.

  1. Go to Settings › API Keys.
  2. On the key’s row, open More actions and select Revoke.
  3. Click Revoke to confirm.

The Storefront publishable key card has one key for each store. This key can only read your catalog and act as a shopper, and it only accepts browser requests from the sites listed under Allowed sites (managed automatically). EcomWeb adds your store’s address, your custom domain, localhost and 127.0.0.1 (any port), and the sites of themes you connect from your own server. Requests that carry no Origin header, such as server-side requests, are not limited by this list.

  1. Go to Settings › API Keys.
  2. On the Storefront publishable key card, click Copy.
  3. Paste the key into your storefront’s configuration.

Your storefront sends this key in the x-storefront-api-key header. To use it on a website that runs on your own server, see the self-hosted site guide.

Roll the key to retire the old one, for example when you change who builds your storefront.

  1. On the Storefront publishable key card, click Roll key.
  2. Click Roll key again to confirm.
  3. Click Copy to get the new key.
  4. Update your storefront with the new key.

The old key keeps working for 7 more days, then stops. A line under the new key shows the date the old key stops working.

Do I need an API key to use the EcomWeb CLI on my own computer?

Section titled “Do I need an API key to use the EcomWeb CLI on my own computer?”

No. Run ecomweb auth login and approve the sign-in in your browser. The CLI then uses your own role in each store. API keys are for servers and CI, where no one is there to approve.

EcomWeb does not store keys in a readable form, so you cannot view the key again. Create a new key, update the system that used the old one, then revoke the old key.

Why did a key change to Revoked on its own?

Section titled “Why did a key change to Revoked on its own?”

A key works with the permissions of the person who created it. When that person leaves the store, is removed from it, loses the right to manage keys or transfers ownership, the keys they created are revoked. The small text under the status gives the reason.

What does the Storefront use label on a key mean?

Section titled “What does the Storefront use label on a key mean?”

The dashboard saw that secret key used from a storefront, where anyone can read it. Switch the storefront to the publishable key, then revoke that secret key.