Security

Credentials

• API keys are 256-bit random secrets; the raw key is shown exactly once at creation and never stored — only a SHA-256 hash (for lookup) and a short display prefix are persisted.
• Keys are presented over HTTPS only; requests without a recognized ORN key prefix are rejected before any database lookup.
• The environment is encoded in the key prefix and must match the application’s environment, making cross-environment misuse structurally impossible.
• Revocation is immediate: a revoked credential fails authentication on its next use.

Authorization and isolation

• Scopes are granted per application and checked fail-closed before an operation runs; unauthorized calls are never billed.
• Journey, checkpoint, safety and passenger data are isolated per ride-owner organization: reads filter to the organization’s linked platform account.
• Records outside your organization return 404 RESOURCE_NOT_FOUND — the API never confirms the existence of another organization’s data.
• The database is never exposed to API consumers; all resolution runs server-side through the platform’s service layer.

Money

• Wallet debits and free-allowance consumption are atomic — concurrent calls can never double-spend an allowance slot or overdraw the wallet.
• Charged operations that fail server-side are reversed automatically, keyed to the request id.
• A suspended wallet keeps its balance and refuses both debits and credits — tampering protection with manual reconciliation.
• Every charge traces to exactly one request id, one usage record and one wallet ledger entry.

Audit trail

The API is built to be on the record. Every request produces a request record (method, path, status, duration); every billed call produces a usage record (pricing version, tier, price, classification); every state change produces a domain event; and every webhook delivery attempt is recorded with its response. All of it correlates through the request id returned in x-request-id.

Operational surfaces

• Internal workers (event delivery and scheduled jobs) are gated by server-side secrets with constant-time comparison and are unreachable from the public API surface.
• Errors never leak internals: unexpected failures collapse to a generic 500 INTERNAL_ERROR, with details logged server-side only.
• Sandbox keys cannot write (see Sandbox), so test credentials can never mutate production records.