Create and manage API keys

An API key lets a server, an automation tool or CI read and write your store 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.

The API keys page also has a publishable key for your storefront. It is used in theme code that runs in the browser, and it can only do what a shopper can do.

Create a secret key

1. Go to Settings › API keys.
2. Click Create API Key.
3. Enter a Key Name, for example the name of the system that will use the key.
4. Under Key Type, keep Standard, or choose Read Only if the system only needs to read data.
5. 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.
6. Check the Expires At date. A new key expires after 90 days. You can pick a different date in the calendar.
7. Click Create.
8. In the API Key Created box, click the icon of two overlapping sheets Copy next to the key.
9. Paste the key into your system’s secret storage, for example a server or CI environment variable.
10. Click I've saved this key.

On a phone, tap the menu icon in the top left corner, select Settings, then tap the table icon next to Settings to choose API keys. The Create API Key button is under the three-dot icon at the top of the page.

To make the key accept requests only from your server, enter your server’s IP address under IP Whitelist and press Enter. Enter one IP address at a time, pressing Enter after each. Do not enter an IP range such as 10.0.0.0/24, only single addresses. If you leave it empty, the key accepts requests from any address.

Use a secret key

Send the key in the x-api-key header of every request to the EcomWeb API. The key only works for the store that created it, and only for the scopes you chose.

With the EcomWeb CLI, put the key in the ECOMWEB_API_KEY variable. The key takes priority over your sign-in session, and the CLI does not write the key to disk.

# Read the product list with an API key, for example in CI
$ ECOMWEB_API_KEY=<secret key> ecomweb products list --store-ref <store ref>

Edit or pause a key

1. Go to Settings › API keys.
2. On the key’s row, click the three dots More actions.
3. Select Edit.
4. Change the name, scopes, IP list or expiry date.
5. To pause the key, turn off Active.
6. Click Save Changes.

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

Revoke a key

1. Go to Settings › API keys.
2. On the key’s row, click the three dots More actions.
3. Select Revoke.
4. Click Revoke to confirm.

Get the publishable key for your storefront

The Storefront publishable key card has one key ready for each store. This key can only read the catalog and act like a shopper, and it only accepts requests from the sites under Allowed sites (managed automatically). EcomWeb automatically adds your store’s address, your custom domain, localhost and any self-hosted site you have connected to 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 with a website that runs on your own server, see Connect a self-hosted site.

Roll the publishable key

Roll the key when you want to get rid of 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 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. Under the new key, a line shows the date the old key stops.

Frequently asked questions