Getting started
Authentication
Every request carries an API key. A key belongs to a project, a project belongs to your account, and the account's plan decides what the key may read.
On this page
Send the key#
Send the key in a header on every request, in one of two forms. Both are treated the same.
Request headers
Authorization: Bearer om_...
X-API-Key: om_...curl -sS "https://api.ordermap.si/v1/account" \
-H "Authorization: Bearer $ORDERMAP_API_KEY"const res = await fetch("https://api.ordermap.si/v1/account", {
headers: { Authorization: `Bearer ${process.env.ORDERMAP_API_KEY}` },
});
console.log(await res.json());/v1/account returns your plan, entitlements and rate limits, so it is the quickest way to check that a key works.
Keys, projects and accounts#
- Create and revoke keys in the Developers tab of the OrderMap terminal. A key belongs to a project and a project belongs to your account.
- A key is 67 characters:
om_followed by 64 hexadecimal characters. It is shown once, when you create it. Only a hash is stored, so a lost key cannot be recovered: create a new one. - All keys of an account share the account's plan, its rate limits and its WebSocket connection slots. A new key does not add capacity.
- Revoking a key or deleting its project takes effect at once. WebSockets opened with it are closed at the next 30-second check.
- An account can have a limited number of projects and keys. By default that is 5 projects, 10 active keys per project and 20 key creations per day.
Endpoints that need no key#
/v1/status (service health) and /v1/openapi.json (the OpenAPI 3.1 document) answer without a key. Requests without a valid key share a separate budget per client network, described under rate limits.
Authentication errors#
| Status | Code | Meaning |
|---|---|---|
| 401 | api_key_required | No key was sent. |
| 401 | invalid_api_key | The key is unknown or revoked, or its project is inactive. |
| 401 | invalid_project, account_unavailable | The key's project is inactive, or the account is unavailable. |
| 403 | api_subscription_required | The account has no active API subscription. |
| 403 | account_suspended | The account is suspended. Contact support. |
| 429 | cooldown | Many failed attempts from one network cause a temporary block. Wait Retry-After. |
The full list, with retry guidance, is in Errors.
API subscriptions#
API subscriptions (API Developer and API Pro, see Plans and entitlements) are separate from terminal subscriptions: a terminal plan does not grant API access and the reverse.