Authentication

The OpenBoxes Lift API uses API keys. You create a key in the portal, then send it in the X-API-Key header on every request. There is no login step and no session cookie to manage.

Creating an API Key#

  1. Sign in to your portal at https://app.openboxes.cloud.
  2. Open the API tab and go to API keys.
  3. Click Create key, give it a name, choose its scopes (read, write, reporting, admin) and an optional expiry date.
  4. Copy the key when it is shown. The secret is displayed once and cannot be retrieved later.

Only the four scope values above are accepted; any other value is refused with 400. Only the account owner can create API keys. Invited teammates can open the API tab and its API keys page, but they cannot list, create or revoke keys there: the page shows "Couldn't load your API keys", and Create API Key tells them they don't have permission. The admin scope can only be added by that account owner; an API request asking for it from anyone else returns 403. The portal roles you assign teammates (Admin, Manager, User, Viewer) govern their access to your OpenBoxes instance and do not grant this.

The account owner sees every key on the account, including any a teammate holds, and can revoke it. The Created by column shows who created each key.

The admin scope is what lets a key manage your webhooks (see Webhooks). It is the one scope the platform enforces today; the rest are recorded on the key but not yet checked (below). The reporting scope is for the Reporting API: give it to keys your reporting tools use, so they keep working once scopes are enforced.

The Create dialog also offers Include values to the account owner. It lets that key's Reporting API responses carry stock value, prices and order amounts; without it a key returns quantities only. You can turn it on or off later from the key's menu on the API keys page.

An expiry date is optional and can be set up to one year ahead. When you set one, the key stops working at the end of that day (UTC). Allow a few minutes for it to take effect everywhere, because key checks are cached for up to five minutes and an expiry is a moment passing rather than something we can announce. After that every request with it returns 401. Create the replacement key before the old one lapses.

A key looks like keyId.secret (an identifier, a dot, and a secret). Treat the whole string like a password.

Keys are scoped to a single tenant. A key created for acme only works against https://acme.openboxes.cloud; using it against another subdomain returns 403. The platform API host https://api.openboxes.cloud (webhook management and the Reporting API) always works on the account the key belongs to.

Revoking a Key#

Revoking is not the same as letting a key expire. When you revoke a key in the portal (API tab, API keys, Revoke), it stops working within seconds: every request made with it returns 401 from then on. The account owner can revoke any key on the account, including one someone else on the account created. A request that was already in flight when you revoked may still complete, but nothing new is accepted. The five-minute caching note above applies to expiry dates only.

Revoke straight away if a key may have leaked, and create a replacement.

Authenticating Requests#

Send the key in the X-API-Key header on every request:

# List products
curl -H "X-API-Key: $OB_API_KEY" \
  https://acme.openboxes.cloud/api/v1/products

# Create a new product
curl -X POST \
  -H "X-API-Key: $OB_API_KEY" \
  -H "Content-Type: application/json" \
  https://acme.openboxes.cloud/api/v1/products \
  -d '{"name": "Amoxicillin 250mg", "category": {"id": "cat-123"}}'

Requests without a valid key receive 401 Unauthorized. Requests whose key belongs to a different tenant receive 403 Forbidden.

Scopes are recorded and not yet enforced on the OpenBoxes data API, with one exception. On the data API (https://{tenant}.openboxes.cloud/api/v1/...) the platform does not refuse a request because the key lacks a scope. What a key can do there is governed by the OpenBoxes permissions of the user who created it, and broader enforcement is planned, with no date. The exception: managing webhooks with an API key requires the admin scope: a key without it is refused with 403. Until the rest ships, treat the other scopes as a label and control data access with the OpenBoxes permissions of the person who created the key.

How It Works#

Behind the scenes the platform exchanges your API key for an authenticated OpenBoxes session, scoped to your tenant. You never see or manage that session; you only send the X-API-Key header. In the current release a key acts as the OpenBoxes user of the person who created it, so its data visibility matches that user's permissions inside OpenBoxes. The Reporting API is different: it reads our daily copy of your whole account's figures, not OpenBoxes, so every key bound to the account sees the same reporting data (quantities only, unless the account owner turned on Include values for that key).

Best Practices#

Secure Credential Storage#

Never hardcode keys in source code. Use environment variables or a secrets manager:

export OB_API_KEY="$(vault read -field=key secret/openboxes-lift)"

curl -H "X-API-Key: $OB_API_KEY" \
  https://acme.openboxes.cloud/api/v1/products

Rotate Keys Regularly#

Create a new key, switch your integration over, then revoke the old one from the API keys section. Revoking takes effect within seconds, so do it as soon as the switch-over is done rather than leaving the old key alive. Set an expiry date on keys used by short-lived jobs.

Use Least Privilege#

Only the account owner creates API keys, and on the data API a key acts as the OpenBoxes user of the person who created it. Create one key per integration and give it the narrowest scopes that integration needs (for example reporting for a reporting tool), so each integration can be revoked on its own. Scopes are not yet enforced on the data API, but setting them is still worth doing. It documents intent and will apply once broader enforcement ships. The admin scope is the exception and behaves as you would expect already: give it only to keys that manage webhooks, because a key without it is refused there with 403.

Limitations#

  • A key acts as the user of the person who created it: a key inherits that person's OpenBoxes permissions. Per-key user identities are a planned enhancement.
  • Scopes are not yet enforced on the data API: a key's scopes are recorded and displayed, but no data-API request is refused for missing one. Broader enforcement is planned, with no date. One exception is live today: managing webhooks with an API key requires the admin scope, and a key without it is refused with 403.
  • One tenant per key: a key only works against the subdomain it was created for, and on https://api.openboxes.cloud for its own account only.

Guides

From the blog