Your first OpenBoxes API call with an API key

OpenBoxes has a REST API, and on OpenBoxes Lift you reach it with an API key. There is no login request and no session cookie to keep alive: you send the key in one header on every request. This article takes you from no key to a first successful call, explains what each response code means, and covers the handful of things worth knowing before you build anything real on it. The reference is in the docs, starting at API overview.

If you have used the API of a self-hosted OpenBoxes, you logged in with POST /api/login and carried a JSESSIONID cookie from then on. On Lift you do not call the login yourself; the key replaces it.

1. Create a key#

Only the account owner can create API keys. Teammates can open the page but cannot list, create or revoke keys there.

1. Sign in to the portal at app.openboxes.cloud.
2. Open API in the left navigation, then Manage API keys.
3. Select Create API Key. Give it a name that says what it is for, for example "stock sync script".
4. Choose its scopes: read, write, reporting or admin. For a first read-only script, read is the honest choice.
5. Optionally, set an expiry date, up to one year ahead.
6. Copy the key. It is shown once and cannot be shown again. It looks like an identifier, a dot and a secret; treat the whole string like a password.

What the scopes do today#

Be clear about this before you rely on it. On the OpenBoxes data API, scopes are recorded on the key but not yet enforced. No data request is refused because a key lacks a scope. What a key can do there is decided by the OpenBoxes permissions of the person who created it: the key acts as that person's OpenBoxes user, at their default location.

The one exception is webhook management, which requires the admin scope today. Set scopes to match what the integration does anyway. They document your intent, and they will apply once broader enforcement arrives (no date has been set).

2. Make the call#

Put the key in an environment variable rather than in your code or your shell history:

export OB_API_KEY="paste-your-key-here"

Then list the first ten products in your catalog. Replace acme with your instance's subdomain:

curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/products?max=10&offset=0"

The address is your instance's address plus /api/v1. There is no /openboxes in the path, even though you see one in the browser. Anything the OpenBoxes project documents as /api/products is /api/v1/products on Lift.

A successful answer is JSON with the products under data and a totalCount of every matching product, not only the ten returned:

{
  "data": [
    { "id": "…", "productCode": "…", "name": "…" }
  ],
  "totalCount": 550
}

(The count above is only an example.) Response shapes are not uniform across OpenBoxes endpoints: some lists come back as a bare array. Check the docs page for each endpoint you use.

3. Read the answer when it is not a 200#

• 401: no key, a mistyped key, or one that was revoked or has expired.
• 403: the key belongs to a different instance. A key works only against the instance it was created for.
• 429: too many requests. Wait for the number of seconds in the Retry-After header, then continue.

Successful responses carry X-RateLimit-Limit and X-RateLimit-Remaining, so a script can see how much of its hourly allowance is left. Your plan's limits are on Rate limits.

4. Always page through lists#

Without max, an OpenBoxes list endpoint returns every record in one response. On a large catalog that is slow for you and heavy for your instance. Always pass max, and move through the list with offset: offset=0, then offset=10, and so on, until you have totalCount records, on endpoints that return one. Not every list does, and not every list honours max, so check each endpoint's page in the docs.

To search, add q, which matches name, product code, description, manufacturer and vendor:

curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/products?q=ibuprofen&max=25"

5. Keep the key safe#

• Call the API from a server or a script, never from a web page. A key in page JavaScript is visible to anyone who opens the page.
• One key per integration. You can then revoke one without breaking the others.
• Revoke at once if a key may have leaked. A revoked key stops working within seconds. An expiry date is different: allow a few minutes after the end of that day (UTC) for it to take effect everywhere.
• Rotate by overlap. Create the new key, switch the integration over, then revoke the old one.
• Not against a staging copy. API keys are refused against a staging copy of an instance, so test your integration against a trial instance instead.

Where to go next#

• Products, locations, inventory and stock movements: the API docs cover each one, and say plainly which endpoints we have verified on Lift. If an endpoint is not in the docs, we have not verified it; check with support before building on it.
• Report figures rather than live data: the Reporting API lives on a different host, api.openboxes.cloud, and serves our daily figures for tools like Power BI and Excel. Your stock data in Excel or Power BI shows it in use.
• Being told when something happens instead of asking: webhooks. Reacting when a purchase order is received builds one end to end.

Summary#

• The account owner creates a key under API, Manage API keys; it is shown once.
• Send it in the X-API-Key header to https://<your-subdomain>.openboxes.cloud/api/v1/....
• Scopes are recorded but not yet enforced on the data API; the key acts as its creator's OpenBoxes user.
• Always pass max and offset on lists, keep keys out of web pages, and revoke a leaked key straight away.

Everything else that connects to OpenBoxes Lift is on Integrations.