Guide
Scopes
The ORN API scope catalogue, how scopes are granted to applications, and how they are enforced on every call.
What scopes are
Scopes are permission labels granted at the application level. An application can only call operations whose required scope it has been granted, and every credential of that application inherits its scopes. Authorization is fail-closed: if a required scope is not granted, the call is refused.
The scope catalogue
| Scope | Grants |
|---|---|
| journeys:read | Read journey records, states, boarding, driver, vehicle, QR metadata, timeline and monitoring data. |
| journeys:write | Create, update, activate and cancel journeys. |
| checkpoints:read | Read planned and recorded journey checkpoints and history. |
| checkpoints:write | Submit authorized checkpoint observations. |
| safety:read | Read safety events, context and evidence for your journeys. |
| safety:write | Submit authorized safety events and request operational safety assessments. |
| passengers:read | Read aggregate passenger experience and sentiment insight (enterprise subscription required). |
| intelligence:read | Read ORION analysis, route intelligence and specialized insight operations. |
| notifications:read | Reserved for the planned Notifications capability (event delivery). |
How scopes are enforced
Every priced operation declares the scopes it requires in the API pricing register (pricing version API-PRICING-2.0). When a call arrives, the billing reservation step checks the operation’s authorization requirements against your application’s granted scopes before the operation runs.
- Missing scope → 403 CAPABILITY_NOT_AUTHORIZED. The response names the capability or requirement that was not satisfied.
- Subscription-gated operations (for example Passenger Intelligence, which requires the enterprise subscription) fail the same way when the organization’s tier does not match.
- The check happens before billing and before business logic — an unauthorized call is never charged.
Scopes are granted by ORN when your application is set up. If an operation you need returns CAPABILITY_NOT_AUTHORIZED, contact the support desk to review your application’s grants.
Data isolation beneath scopes
Scopes control what kinds of operations you may call; tenant isolation controls whose records you can touch. Journey, checkpoint, safety and passenger operations are anchored to the ride-owner account linked to your organization: reads filter to your records, and a record that exists but is not yours returns 404 RESOURCE_NOT_FOUND rather than revealing that it exists.