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 API key | No header, a malformed key, or a revoked key | Check the header; ask the owner for a new key |
| 403 | API access, webhooks and Zapier are part of the Pro and Business plans. | The key is fine, the business's plan is not | Ask the owner to upgrade or renew |
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. It stops working on the next request. To rotate without downtime: the owner creates a second key, you switch to it, then the owner revokes the first.
Ordina records when each key was last used, and shows it to the owner. Individual requests are not logged.
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.