API keys

The storefront API reads the shop, products and collections without a key, the same things the hosted shop shows. A key adds two things an open request can't have:

• Draft products, so a staging website can show a product before the shop makes it active.
• A count of requests, so you can see which website or server calls and how often, when each one uses its own key.

With GraphQL, a key also tells Commerce Orbit which shop to read, so you don't need ?organisation=.

Open API keys under Developers in the sidebar. Everyone can see the list. Only Admins can create, rename, revoke and remove keys.

Create a key

1. Choose New key.
2. Give it a name that says where it is used, such as northwilds.com, preview.
3. Under Expires, choose Never, In 30 days, In 90 days or In a year. A key for a live website usually never expires.
4. Switch on draft products only for a preview of your website.
5. Create the key, then copy it straight away.

The key is shown once. Commerce Orbit stores only a hash of it, so it can't show it to you again; the list shows its first 12 characters, such as com_pk_Ab3d…, so you can tell keys apart. If a key is lost, revoke it and create another.

Two kinds of key

With a com_sk_ key, the product endpoints and GraphQL's products and product also return draft products, with "status": "draft". Answers with drafts are never cached. Collections still show only active collections, and carts never take draft products.

Send the key

Send the key in a header, either way:

Authorization: Bearer com_pk_…X-Api-Key: com_pk_…

For example, a preview build on your server:

1const response = await fetch("https://app.bifrostorbit.com/commerce/api/public/northwilds/products?tag=winter", {2  headers: { Authorization: `Bearer ${process.env.COMMERCE_ORBIT_KEY}` },3});4const { data } = await response.json();

A key that is wrong, revoked, expired or belongs to another shop gets 401, even on reads that need no key, so a mistake doesn't go unnoticed. The message says which, such as "This API key has been revoked. Create a new one under API keys in Commerce Orbit."

Revoke and remove

Choose ⋯ next to a key, then Revoke. It stops working on its next request and can't be switched back on. A revoked key can then be removed; Undo brings it back for a few seconds. A key must be revoked before it can be removed. Rename changes only the name: the key keeps working. Every change is in the audit trail.

The list shows whether each key reads drafts, how many requests it made in the last 30 days, and the day it was last used.

Try a key

In the API playground, paste a key at the top. Requests then run with it, and the curl and JavaScript you copy include it.