API Scopes
API keys are created and managed from the Dashboard. When you create an API key, you choose which scopes to grant it. Scopes determine which environment the key can access and which operations it's allowed to perform.
A request only succeeds if the API key includes every scope that the operation requires. If a required scope is missing, the request is rejected.
Environments
All Aboard exposes two independent environments, each with its own set of scopes:
- Live (
live): the production environment where real bookings and payments happen. - Test (
test): the sandbox environment for development and integration testing.
The base live or test scope is required to access that environment at all. Without it, no other scope for that environment takes effect. The more specific scopes (such as live:orders:read or test:payments:wallet) grant additional, narrower permissions on top of that base access.
A single API key may include scopes for both environments, but most integrations use a separate key per environment.
Available scopes
Live environment
| Scope | Grants |
|---|---|
live |
General access to the live environment, including creating orders |
live:orders:read |
Access orders in the live environment |
live:payments:invoice |
Create orders in the live environment using invoice as the payment method |
live:payments:stripe |
Create orders in the live environment using Stripe as the payment method |
live:payments:wallet |
Create orders in the live environment using wallet credits as the payment method |
live:passenger_profiles:read |
Search passenger profiles in the live environment |
Test environment
| Scope | Grants |
|---|---|
test |
General access to the test environment, including creating orders |
test:orders:read |
Access orders in the test environment |
test:payments:invoice |
Create orders in the test environment using invoice as the payment method |
test:payments:stripe |
Create orders in the test environment using Stripe as the payment method |
test:payments:wallet |
Create orders in the test environment using wallet credits as the payment method |
test:passenger_profiles:read |
Search passenger profiles in the test environment |
Payment method scopes
Each payment method has its own scope. For a payment method to be accepted when creating an order, the matching scope must be included in the API key:
- Wallet: requires
live:payments:wallet/test:payments:wallet - Payment gateway (Stripe): requires
live:payments:stripe/test:payments:stripe - Invoice: requires
live:payments:invoice/test:payments:invoice
Which payment scope a request needs depends on how the cost center you bill against is configured. See Payment Methods for details on each payment flow.
Choosing scopes
Grant a key only the scopes it actually needs. For example, a key used solely to look up order status only needs live and live:orders:read, not any of the payment scopes.
Passenger profile scope
Searching passenger profiles with passengerProfiles requires live:passenger_profiles:read / test:passenger_profiles:read. Without it the search is refused with FORBIDDEN. Reading the signed-in user's own profile through me.profile needs no extra scope.
Keys on public pages
A key with orders:read reads every order on your sales agent, so it must stay on your server. So must a key with passenger_profiles:read, which reads the names, contact details, birth dates and travel cards in the profiles of every company you book for. When a public page needs to show or refund one order (an order confirmation page, or the Refund Manager embed), mint an access token for that order instead. Minting needs orders:read, plus payments:stripe if the page is to refund the order as well.
For embeds that only book and pay, a key with only the base scope and *:payments:stripe (for example live and live:payments:stripe) is still the right credential. See Configuring embeds safely.