API docs
Authentication
Every request carries the shop's API key as a bearer token:
Authorization: Bearer ir_live_2mB7wQ…
A key has three parts:
- A prefix:
ir_live_for live,ir_test_for the sandbox. - 40 random base62 characters, roughly 238 bits of entropy.
- A display form: Iron Register only keeps the first 12 characters and the last 4 for showing the key, plus a SHA-256 hash. The full key can't be recovered. If it's lost, roll it.
A key acts as itself, not as a staff member. Every change it makes is written to the shop's audit log as "… by API key Flxpoint".
What's checked on every request
The checks run in this order, and each one fails closed:
| Check | Failure |
|---|---|
The header holds an ir_live_ or ir_test_ key |
401 INVALID_API_KEY |
| The key's prefix matches this server | 401 WRONG_ENVIRONMENT |
| The key exists and isn't revoked or expired | 401 INVALID_API_KEY |
| The caller's IP is in the key's allowlist (if the key has one) | 403 IP_NOT_ALLOWED |
| The shop's subscription is in good standing | 402 with TRIAL_EXPIRED, BILLING_PAST_DUE, SUBSCRIPTION_CANCELED or PLAN_REQUIRED |
| The shop's plan includes the API | 402 API_NOT_IN_PLAN |
| The shop is under its rate limit | 429 RATE_LIMITED |
| The key has the permission the endpoint needs | 403 INSUFFICIENT_SCOPE |
For /v1/range/*: the shop has the Range add-on |
402 RANGE_ADDON_REQUIRED |
Restricting a key
The owner sets these under Settings → Developers → API keys. Changes take effect on the key's next request.
- Permissions. None, Read or Write per resource. See Permissions.
- Locations. A key limited to some stores only sees orders, inventory, returns, purchase orders, serialized units, locations and range bookings at those stores. Records at other stores behave as if they don't exist: they're left out of lists, and fetching one directly gives
404. Products and customers belong to the whole shop, so they aren't filtered by location. - IP allowlist. Up to 50 IPv4 or IPv6 addresses or CIDR ranges, such as
203.0.113.0/24. Requests from anywhere else get403 IP_NOT_ALLOWED. Use this for server-to-server integrations with fixed egress IPs. - Expiry. An optional date after which the key stops working.
Rolling and revoking
- Roll. Creates a new key with the same settings. The old key keeps working for a grace period the owner chooses, from 0 to 168 hours (24 by default), then expires. Deploy the new key within that window.
- Revoke. Stops the key immediately and permanently.
Keep keys on servers
API keys are server-to-server credentials:
- Never put one in a web page, a browser extension, a mobile app or a public repository.
- The API sends no CORS headers, so browsers can't call it directly.
- A key can read customer contact details and change stock. Treat it like a database password.
If a key leaks, revoke it and create a new one.