Store API keys

Connect a store's own systems — an ERP, a warehouse, an accounting export — straight to the Orbit API with a credential the merchant mints themselves. No partner account, no plugin, no OAuth handshake.

When to use an API key (and when to build a plugin)

Everything else on this site describes plugins: software one party builds and many merchants install, authorised through OAuth consent. That machinery earns its keep when there is distribution — a marketplace listing, many stores, per-install consent.

An API key is for the other case: one store, connecting to systems its own team runs or commissioned. There is nothing to distribute and nobody to consent except the merchant, who creates the key in their own dashboard.

If you are building for many stores, stop here and read Getting started. If you are wiring up one store you control, read on.

Creating a key

In the store dashboard: Settings → API Keys → Create API key.

1. Name it after the system that will hold it — "Sage 200 connector", "Warehouse sync". The name appears in the store's Activity Log next to everything the key changes, so make it recognisable.
2. Pick scopes. The key can only call endpoints its scopes cover — same vocabulary and enforcement as plugin tokens, documented in the Scope Catalog. Grant the least the system needs.
3. Copy the key immediately. It is shown exactly once, at creation. Orbit stores only a fingerprint, so a lost key cannot be recovered — only revoked and replaced.

Keys look like oc_sk_… followed by 43 characters. A store can hold up to 10 active keys — enough for one per connected system with room to rotate. An optional expiry date is available at creation; by default a key stays valid until revoked.

Making calls

Send the key as a bearer token to the public API. The store is derived from the key itself — no store id header or parameter is needed on /v1 endpoints.

GET /v1/orders?limit=20 HTTP/1.1
Host: api.myorbitcommerce.net
Authorization: Bearer oc_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

const response = await fetch(
  'https://api.myorbitcommerce.net/v1/orders?limit=20',
  { headers: { Authorization: `Bearer ${process.env.ORBIT_API_KEY}` } },
);
const { data } = await response.json(); // { items, meta }

Responses arrive in the platform's standard envelope { statusCode, message, data, timestamp } — read the data field, exactly as described in Authentication & tokens.

The /v1 resource endpoints in the API Reference — products, orders, customers, taxonomies, carts, tracking scripts, webhooks — accept an API key, gated by the same scopes as plugin tokens. (The plugin-only surfaces — billing, email sending, plugin settings — require scopes a key cannot hold, so they stay out of reach by construction.) Polling GET /v1/orders?updatedFrom=… on a schedule is the simplest reliable integration shape — an on-premise service behind a corporate firewall needs nothing inbound at all.

Scopes a key can hold

A key can be granted the resource scopes — product:*, order:*, customer:*, taxonomy:*, cart:*, tracking-script:* — plus webhook:* for managing the store's own webhook subscriptions.

A few families are not grantable to keys because their endpoints only make sense for an installed plugin: billing:* (plugin monetisation), email:send (sends attributed to a plugin), and settings:* (a plugin's own settings storage). The dashboard's scope picker simply does not offer them; the API rejects them with 400 if requested directly.

Rate limits

Limits are per key, per minute, and generous enough for bulk work:

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix time). Past the limit you receive 429 Too Many Requests with a Retry-After header — back off until then.

Errors you will meet

Lifecycle

Revocation is immediate. Deleting a key in the dashboard takes effect on its next request — there is no cache to wait out. If a key may have leaked, revoke first and rewire after.

Scopes are fixed at creation. A key's access never changes after it is minted — there is deliberately no way to edit scopes on a live key, because widening them would silently escalate a credential some system already holds, and it would blur the activity log's answer to "what could this key do at the time?". To change access, use the rotation recipe below: create a new key with the scopes you want, switch your system over, revoke the old one.

Rotation is a recipe, not a mechanism. Keys do not rotate themselves — an unattended service has nobody present to re-consent when an automatic rotation fails, so Orbit deliberately keeps keys long-lived. When you want to rotate: create the successor key, deploy it to the system, confirm traffic, then revoke the predecessor. Two keys can be live side by side for as long as the migration needs.

Watch last used. The key list shows when each key last made a call. A key whose activity you cannot account for should simply be revoked — creating a replacement costs a minute.

Writes are attributed. Every change a key makes appears in the store's Activity Log under the key's name, alongside changes made by staff and plugins. Name keys so that log reads well.

Security practices

• Server-side only. An API key in a browser, mobile app, or public repository is public. Keep it in your server's secret manager or environment.
• One key per system. Separate keys for the ERP and the warehouse mean revoking one does not break the other — and the Activity Log tells them apart.
• Least scopes. A reporting job needs order:list, not order:update.
• Never log it. Redact the key from request logs and error reports; the oc_sk_ prefix makes it easy to scan for.

Next steps

• Push events out instead of polling: Webhooks — a key with webhook:* scopes manages the store's own subscriptions, signed with a per-subscription secret.
• The full endpoint surface: API Reference.
• The exact scope strings: Scope Catalog.