API keys and authentication
How API keys are created, sent, stored and revoked, what each authentication error means, and how to handle many businesses.
Every request to the API is authenticated with an API key that belongs to one business.
Creating a key
- The business owner opens Integration, then API keys, and creates a key with a name, for example the name of your app.
- The key is shown once. Ordina keeps only a fingerprint (a SHA-256 hash), so nobody, including Ordina, can show it again.
- A business can have up to 10 active keys. Revoked keys do not count.
Keys look like ord_live_ followed by 40 letters, digits, hyphens and underscores.
Sending it
Put it in the Authorization header of every request:
Authorization: Bearer ord_live_8yQm2...
Nothing else is needed: no signing of requests, no session, no cookies. Always call over https.
Errors
| Status | Body | Meaning | What to do |
|---|---|---|---|
| 401 | Invalid or missing credentials | No header, a malformed or revoked key, or an expired access token | Check the header; refresh the token or ask the owner for a new key |
| 403 | API access, webhooks, Zapier and connected actions are part of the Business plan. | The key is fine, the business's plan is not | Ask the owner to upgrade or renew |
| 403 | This business's Ordina account is not active. | The business is suspended or closed | Nothing to fix on your side |
A 401 never tells you whether a key once existed, so a guessed key learns nothing.
Revoking and rotating
The owner revokes a key in Integration, API keys. On the next request:
- the key stops working (401);
- every webhook endpoint, connected action and intake the key created is switched off (the owner can switch them back on, nothing is deleted);
- if the owner ticks Also remove the knowledge it added (it is ticked unless they untick it), every text the key pushed is deleted.
Rotating without downtime: the owner creates a second key and you switch to it. Because webhooks, actions and knowledge belong to the key that made them, subscribe your webhooks, register your actions and push your knowledge again with the new key, then the owner revokes the first. The owner switches the new actions on.
Ordina records when each key was last used, and shows it to the owner. Individual requests are not logged.
What belongs to your key or app
Every webhook endpoint, connected action and piece of pushed knowledge made through the API records the key, or the connected app, that made it. The owner sees its name next to each one in the dashboard.
GETlists only what your key or app made.GET,PATCHandDELETEon one item answer 404 when another key or app made it, exactly as if it did not exist, and change nothing. The one exception isDELETE /webhooks/{id}, which always answers 204 so an unsubscribe can be repeated safely; it removes only an endpoint that is yours.- Knowledge keys are yours alone: two apps can both push
faqand keep two separate texts. - A connected app keeps what it made when it reconnects, because it is recorded against the app, not one token.
- Older items are shared. Webhooks, actions and knowledge made through the API before Ordina started recording who made them have no owner, so every key and app of the business can still list, replace and delete them. An existing subscription can always unsubscribe. For the same reason, revoking a key or disconnecting an app does not switch them off; the owner does that in the dashboard.
- Items the owner adds in the dashboard are never listed, changed or deleted through the API.
- Intakes are never shared. Every intake records the key or app that made it, so only that key or app lists, changes or deletes it and reads its responses. There are no older shared intakes.
- If Ordina cannot check who owns an item at that moment, the request answers 503 with
Retry-Afterand changes nothing. Retry after that many seconds.
API keys or Connect to Ordina?
An API key suits your own scripts, or a one-off setup the owner does by hand. A platform that many businesses will connect should use Connect to Ordina instead: the owner clicks a button in your app, approves on Ordina, and you receive a token for their business. Nothing is copied or pasted, and the owner can disconnect you at any time.
Working with many businesses
A platform that serves many businesses holds one key per business and stores it against that business in your system. Call GET /api/v1/me once when a key is added to learn the business's id, handle, currency and country, and to confirm the key works.
Keeping keys safe
- Keep keys on your server or in a secrets manager. Never put one in a website, a mobile app, or a repository.
- A key can read customers' names, emails and phone numbers. Treat it like a password to that data.
- Use a separate key per app or environment, named so the owner can tell them apart. If one leaks, only that one is revoked.
