Scopes
The permissions an app can ask for, what the hotel sees for each, and which operations each one unlocks.
Scopes limit what an app token may do. You choose the most your app may ask for when you register it; each authorize request asks for those or fewer; the hotel sees each one in plain words and allows them together.
API keys made by hand on Settings → Partner API have no scopes: they can do everything at their property.
The scopes
| Scope | What the hotel sees | Operations it unlocks |
|---|---|---|
property:read | See the property's details, policies and what it offers | GET /properties, GET /properties/{id}/policies |
rooms:read | See room types, rooms, rate plans and extras | GET /properties/{id}/room-types, /rate-plans, /units, /extras |
availability:read | Search availability and prices | GET /properties/{id}/offers |
reservations:read | See bookings | GET /reservations/{id}, GET /properties/{id}/reservations, and booking webhooks |
reservations:write | Make, change and cancel bookings | POST /properties/{id}/reservations, PATCH /reservations/{id}, POST /reservations/{id}/cancel, POST /reservations/{id}/extras |
folios:read | See guests' bills and payments | GET /reservations/{id}/folio, GET /payments/{id} |
folios:write | Add charges and record payments on bills | POST /reservations/{id}/folio/charges, POST /reservations/{id}/folio/payments |
payments:write | Create card payment links on the hotel's Stripe account | POST /reservations/{id}/payment-link |
GET /me and GET /capabilities need no scope. Every connected app can call them.
Write doesn't include read
Each scope stands alone. An app that books with reservations:write and then reads the booking back needs reservations:read as well. The same goes for folios:write and folios:read.
Webhooks need reservations:read
A connection receives booking webhooks only if the hotel allowed reservations:read. Without it, nothing is sent to your webhook address for that property, even if the address is set.
A missing scope
Calling an operation the hotel didn't allow answers 403. Nothing is done.
{
"detail": "This connection was not allowed 'reservations:write'. Ask the hotel to connect the app again with that scope."
}To get a scope you don't have:
- Make sure it is ticked on your app. If your app is Listed, adding a scope sends it back to review; existing connections keep working meanwhile.
- Send the hotel through the consent page again, asking for the new scope. The hotel picks the same property and sees it as already connected; allowing again updates what your app may do there.
The scope field of every token response tells you exactly what the connection may do. Check it rather than assuming.
Ask for the fewest
Hotels see every scope you ask for before they press Allow, and reviewers check that each one is needed.
| You're building | You probably need |
|---|---|
| A booking site or channel | property:read, rooms:read, availability:read, reservations:read, reservations:write |
| A channel manager or PMS sync | rooms:read, availability:read, reservations:read, reservations:write |
| A guest messaging tool | property:read, reservations:read |
| An accounting export | reservations:read, folios:read |
| A payments tool | reservations:read, folios:read, folios:write, payments:write |
Ask for a scope when a feature needs it, not in case it might.
Building something?