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.

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.

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 is valid but lacks the required scope, or belongs to a different tenant, receive 403 Forbidden.

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 its owner's OpenBoxes user (the account that created it), so its data visibility matches that user's permissions inside OpenBoxes.

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. Set an expiry date on keys used by short-lived jobs.

Use Least Privilege#

Give each integration a key with only the scopes it needs. A read-only dashboard should use a read key, not an admin key.

Limitations#

  • Key acts as its owner's user: a key inherits the OpenBoxes permissions of the account that created it. Per-key user identities are a planned enhancement.
  • One tenant per key: a key only works against the subdomain it was created for.