Authentication
Authenticate every request with a partner API key in the X-Partner-Key header.
Every Partner API request carries your API key in the X-Partner-Key header.
curl https://api.sandbox.openroam.com/v1/account/services \
-H "X-Partner-Key: $OPENROAM_API_KEY"Get a key
Create API keys in the OpenRoam partner dashboard of the environment you want to call. A key belongs to the environment that issued it: a Sandbox key works only on the Sandbox host, and a Production key only on the Production host. See Environments.
Treat a key like a password:
- Keep it on your server. Never put it in a mobile app, a browser page or a public repository.
- Read it from a secret store or an environment variable, as the examples on this site do with
$OPENROAM_API_KEY. - Rotate it from the dashboard if it may have leaked, and revoke keys you no longer use.
Permissions
Each key has order permissions. They apply to the order and order item routes:
| Permission | Allows |
|---|---|
read | Reading orders, order items, fulfillment status, amendments and cancellation previews |
manage | Everything read allows, plus placing orders, cancelling, updating and amending items. A manage key always has read too |
Search, browse, catalog and quote routes work with any valid key. A request without the permission it needs is refused with 403 / 10003 (FORBIDDEN).
Key currency
Each key has a currency. Search, catalog and quote prices are in that currency when the request does not name one, and an order is charged in the order's currency. Send currency explicitly when you want another supported currency; GET /v1/currencies lists them.
Services enabled for your account
Each account has its own list of enabled products. GET /v1/account/services returns it:
{
"services": [
{ "productType": "airtime", "enabled": true, "requestable": false },
{ "productType": "hotel", "enabled": false, "requestable": true }
]
}enabledistruewhen the account may search, quote and order the product now.requestableistruewhen you can ask OpenRoam to enable it.
New accounts get eSIMs, gift cards, utility and airtime. OpenRoam enables hotels and flights on request. A request for a product that is not enabled is refused with 403 / 10003, with one details entry per refused product and the reason SERVICE_NOT_ENABLED. A refused request charges, holds and creates nothing. What you sold before a product was switched off keeps working: reads, cancellations, refunds and the eSIM routes after purchase.
Authentication errors
| HTTP | Code | Meaning |
|---|---|---|
| 401 | 10002 UNAUTHORIZED | The key is missing, unknown or revoked, or belongs to another environment |
| 403 | 10003 FORBIDDEN | The key lacks the permission, or the product is not enabled for the account |
See Errors for the error body.