Guide
Authentication
How the ORN API authenticates requests: bearer keys, sandbox and production environments, key lifecycle and failure responses.
Bearer keys
Every request must carry an ORN API key in the Authorization header. Keys issued today look like orn_live_… (production) or orn_test_… (sandbox); the environment is encoded in the prefix.
Authorization: Bearer orn_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXRequests without a valid key are rejected before any business logic runs, so unauthorized callers learn nothing about your data. The raw key is returned exactly once when you create the credential — ORN stores only a SHA-256 hash and a short display prefix, never the raw secret.
Environments
There are two environments, and a key can never be used against an application of the other environment — the prefix inside the key must match the application’s environment, or the request is rejected as UNAUTHORIZED.
| Environment | Key prefix | Behaviour |
|---|---|---|
| Sandbox | orn_test_ | Reads allowed. Write operations are refused with 403 FORBIDDEN. |
| Production | orn_live_ | Full behaviour — reads and writes, metered and billed. |
Sandbox keys are for building and verifying your integration safely: every read works, and every attempted write fails fast with a clear message instead of changing records.
What a key resolves to
A valid key resolves, in one lookup, to a credential → an application → an organization. All three must be active. The application carries your granted scopes and environment; the organization carries your subscription tier and the linked platform ride-owner account that anchors data isolation.
- Credential — may be revoked or expired; neither authenticates.
- Application — carries scopes and environment; may be deactivated.
- Organization — carries subscription tier and platform data link; may be deactivated.
Authentication failures
Authentication failures return 401 UNAUTHORIZED with a specific, safe reason. These are the only distinctions the API makes — everything else about why a key was rejected stays server-side.
{
"code": "UNAUTHORIZED",
"error": "API key has been revoked.",
"request_id": "9f1c…"
}- API key required — no Authorization header, or a non-ORN key format.
- API key is invalid — no credential matches the presented key.
- API key has been revoked / is not active / has expired.
- This application is not active. / This organization is not active.
- API key does not match this application environment.
Key hygiene
- Store keys in a secret manager or server-side environment — never in client-side code, repositories or logs.
- Use sandbox keys while developing; move to a production key only when your integration is verified.
- Revoke and replace keys you suspect have leaked — revocation is immediate on the next request.
- Give each of your integrations its own application so usage and scopes stay separable.