Ta strona nie jest jeszcze przetłumaczona, więc czytasz wersję angielską.
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, GET /properties/{id}/booking-rules |
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, GET /reservations/{id}/cancellation-quote, GET /properties/{id}/arrivals, /departures, /in-house, and booking webhooks |
reservations:write | Make, change and cancel bookings | POST /properties/{id}/reservations, PATCH /reservations/{id} (dates, guests, room type, rate plan; ?dry_run=true to preview), POST /reservations/{id}/cancel, POST /reservations/{id}/extras |
folios:read | See guests' bills and payments | GET /reservations/{id}/folio, GET /payments/{id}, and payment webhooks |
folios:write | Add charges and record payments on bills | POST /reservations/{id}/folio/charges, POST /reservations/{id}/folio/payments, POST /reservations/{id}/folio/lines/{line_id}/complimentary, and giving an extra free (POST /reservations/{id}/extras with complimentary) |
payments:write | Create card payment links on the hotel's Stripe account | POST /reservations/{id}/payment-link, POST /payment-links (several bookings, one page), POST /payments/{id}/void, and payment webhooks |
frontdesk:write | Check guests in and out, and mark no-shows | POST /reservations/{id}/check-in, /check-out, /no-show |
guests:read | See guest profiles | GET /guests, GET /guests/{id} |
guests:write | Add and change guest profiles | POST /guests, PATCH /guests/{id} |
rates:read | See prices and restrictions by date | GET /properties/{id}/rates |
rates:write | Change prices and restrictions (closed, minimum and maximum stay) | POST /properties/{id}/rates, POST /properties/{id}/rates/range |
extras:write | Add, change and take extras off sale | POST /properties/{id}/extras, PATCH /extras/{id}, DELETE /extras/{id} |
policies:write | Change cancellation policies and booking rules (deposit, children, pets, check-in times) | POST /properties/{id}/cancellation-policies, PATCH and DELETE /cancellation-policies/{id}, PATCH /properties/{id}/booking-rules, PATCH /rate-plans/{id}/rules |
negotiation:read | See the private offers your app asked for | GET /properties/{id}/negotiation, GET /properties/{id}/negotiations, GET /negotiations/{id} |
negotiation:write | Ask for private offers inside the hotel's limits, counter, and book the agreed one | POST /properties/{id}/negotiations, POST /negotiations/{id}/counter, /book, /decline |
GET /me and GET /capabilities need no scope. Every connected app can call them.
When you tick scopes on the Developers page, each checkbox shows the endpoints it opens. GET /api/v1/developer/catalogue gives the same list: every scope with its endpoints, and every webhook event.
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 a scope
| Events | Need one of |
|---|---|
reservation.* | reservations:read |
payment.* | folios:read or payments:write |
folio.updated | folios:read |
A connection receives an event only if the hotel allowed the scope it needs. Without it, nothing is sent to your webhook address for that property, even if the address is set. Payment events are also off until you turn them on; you can turn them on only if your app has folios:read or payments:write.
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.
Tworzysz coś?