Scope reference

Every scope Haven declares, what it grants, and what it deliberately does not.

This page is generated from the scope registry the server enforces, so it cannot describe a permission the code does not implement. If a scope is missing here, it does not exist.

There are 45 declared scopes: 24 you can request today, 7 planned, and 14 that no application will ever hold.

Tiers

Every grantable scope carries a tier, which decides how much review it needs before Haven adds it to your application and how it appears on the host consent screen.

Tier	What it means
standard	Ordinary business data the host already sees on their own dashboard, or a reversible change to it. Any approved application may hold it.
sensitive	Third-party personal data, or an irreversible action such as cancelling a stay or messaging a guest. Needs a named sign-off from Haven staff, and the consent screen carries a warning.
restricted	Arrival secrets and money leaving the account. Same sign-off, and the consent row is never pre-ticked: the host has to select it individually.

Scopes you can request

Account

Scope	Tier	What it allows
account:read	standard	See which Haven account it is connected to and what it is allowed to do.

account:read

See which Haven account it is connected to and what it is allowed to do.

Grants:

• The account reference code, display name, time zone and default currency
• Which kind of context the grant acts in: your own account, a workspace seat, or an agency link
• The effective role the grant carries (OWNER, MANAGER or VIEWER)
• The connected app’s own name and client id
• The exact scope list on the token, and when the connection was made
• The current rate-limit budget and reset time

Does not grant:

• The name or email address of the person who approved the connection
• Any listing, booking, guest, message or discount code
• Billing state, subscription plan, payout balance or ad wallet
• The list of other apps connected to this account

Listings

Scope	Tier	What it allows
listings:read	standard	Read your listings: titles, photos, capacity, city, time zone, currency and nightly rate.
listings:write	standard	Change your listing content: title, description, house rules, amenities, capacity, and check-in and check-out times.
listings:publish	sensitive	Archive or hide a listing, and turn booking or instant book on and off.

listings:read

Read your listings: titles, photos, capacity, city, time zone, currency and nightly rate.

Grants:

• Every listing on the account, by reference code, including archived ones
• Title, archived flag, photo set (up to 20) and total image count
• Capacity: maxGuests, bedrooms, bathrooms, halfBaths, beds
• Check-in and check-out times and the listing’s IANA time zone
• City, region and country
• Currency code and the default nightly rate in integer minor units
• pmsOwner and lockedDomains, so a partner can tell what it may write

Does not grant:

• The street address, or any location finer than city — it is not on this surface at any scope
• Wifi password, gate code, directions or check-in instructions — see guidebook:secrets:read
• The guidebook PIN (Property.guideAccessPin), which is a credential and is never returned at any scope
• Guests, bookings, messages or discount codes
• Any change to a listing — see listings:write and listings:publish

listings:write

Change your listing content: title, description, house rules, amenities, capacity, and check-in and check-out times.

Grants:

• The update_listing_content operation, over the content half of a listing’s editable fields

Does not grant:

• Archiving or hiding a listing, or turning booking or instant book on and off — see listings:publish
• Nightly rates, price overrides, promotions and holiday bumps — see rates:write
• Minimum stays and check-in / check-out day rules — see stay-rules:write
• The guidebook PIN, which no scope may write
• The wifi network and password, gate code, directions, check-in method details, check-in instructions or check-in photos. Reading those is guidebook:secrets:read, which is restricted tier and needs a named staff sign-off; a standard content scope must not write by omission what a restricted scope is needed to read.
• The listing’s contact email, phone number, custom domain or URL slug
• Creating or deleting a listing — creation is declared as listings:create and deferred; deletion is not offered

Writes target the PROPERTY_CONTENT, LISTING_CONTENT source-of-truth domains. A listing whose channel manager owns that domain will refuse the write. See Requests and responses.

listings:publish

Archive or hide a listing, and turn booking or instant book on and off.

An app with this permission can stop your listings taking bookings.

Grants:

• The set_listing_market_state operation, over exactly four fields: archived, hidden, allowBooking, instantBook

Does not grant:

• Any other listing field — the operation’s input schema carries these four keys and no others
• Deleting a listing
• Changing prices or rules on a listing it has hidden

Writes target the PROPERTY_CONTENT source-of-truth domain. A listing whose channel manager owns that domain will refuse the write. See Requests and responses.

Calendar

Scope	Tier	What it allows
calendar:read	standard	Read which dates are taken on your listings, and why.
calendar:write	standard	Block dates on your calendar so they cannot be booked, and remove blocks again.

calendar:read

Read which dates are taken on your listings, and why.

Grants:

• Every occupied span on a listing: a booking, a host block, or a sibling listing’s booking in a linked calendar group
• Start and end date of each span and its block type
• The reservation reference code where one exists, so a span can be joined to a booking
• lockedDomains for the listing

Does not grant:

• Who is staying — the guest’s name and email need reservations:read plus guests:read
• What a stay was charged — see reservations:read
• Price overrides or promotions on those dates — see rates:read
• Blocking or unblocking anything — see calendar:write

calendar:write

Block dates on your calendar so they cannot be booked, and remove blocks again.

Grants:

• The block_dates and unblock_dates operations

Does not grant:

• Cancelling or changing a real booking — see reservations:cancel
• Pricing on the dates it blocks — see rates:write
• Minimum stays — see stay-rules:write
• Writing availability on a listing whose AVAILABILITY domain a channel manager owns, or that follows a linked master: those calls are refused with 409 domain_locked before anything is written

Writes target the AVAILABILITY source-of-truth domain. A listing whose channel manager owns that domain will refuse the write. See Requests and responses.

Rates and promotions

Scope	Tier	What it allows
rates:read	standard	Read your nightly price overrides, promotions and holiday price bumps.
rates:write	standard	Create, change and remove nightly price overrides, promotions and holiday price bumps.

rates:read

Read your nightly price overrides, promotions and holiday price bumps.

Grants:

• Per-night price overrides in integer minor units, with the listing’s currency code
• Promotions and holiday price bump rules
• The date window applied to each collection, echoed back
• lockedDomains and pmsOwner for the listing

Does not grant:

• The listing’s base nightly rate — that is on the listing itself, see listings:read
• What a specific booking was actually charged — see reservations:read
• Discount codes — see discounts:read
• Payout amounts or fee breakdowns paid to Haven

rates:write

Create, change and remove nightly price overrides, promotions and holiday price bumps.

Grants:

• create_price_override, update_price_override, delete_price_override, clear_price_overrides_for_range
• create_promotion, update_promotion, delete_promotion
• delete_holiday_price_bump_rule

Does not grant:

• The listing’s base nightly rate, which no v1 scope writes. listings:write covers listing CONTENT and rates:write covers per-night overrides, promotions and holiday bumps; changing the standing nightly price stays a host action in the Haven dashboard.
• Creating a holiday price bump rule: only deletion is on the mobile write surface today, so only deletion is exposed
• Changing what an existing booking was charged — see reservations:refund
• Discount codes — see discounts:write, even though both land in the RATES sync domain

Writes target the RATES source-of-truth domain. A listing whose channel manager owns that domain will refuse the write. See Requests and responses.

Stay rules

Scope	Tier	What it allows
stay-rules:read	standard	Read your minimum-stay rules and your check-in and check-out day rules.
stay-rules:write	standard	Create, change and remove minimum-stay rules and check-in and check-out day rules.

stay-rules:read

Read your minimum-stay rules and your check-in and check-out day rules.

Grants:

• Date-scoped minimum-stay overrides
• Weekly minimum-stay rules
• Check-in / check-out day rules and the per-day blocks they expand into

Does not grant:

• The listing’s default check-in and check-out times — see listings:read
• Availability — see calendar:read
• Changing any of these — see stay-rules:write

stay-rules:write

Create, change and remove minimum-stay rules and check-in and check-out day rules.

Grants:

• create_min_stay_override, update_min_stay_override, delete_min_stay_override
• create_weekly_min_stay_rule, update_weekly_min_stay_rule, delete_weekly_min_stay_rule, sync_weekly_min_stay_rules
• set_check_in_out_blocks — named for what it actually dispatches (setCheckInOutBlocksBulk), not for the mobile command name create_check_in_out_rule, which misdescribes it

Does not grant:

• Deleting a legacy check-in / check-out RULE row: the mobile command delete_check_in_out_rule declares codes: ['property'] but its action takes only { ruleId }, so the declared code is dead and the command is not reachable through reference codes. Excluded from v1 rather than shipped broken
• Blocking dates — see calendar:write
• Pricing — see rates:write

Writes target the BOOKING_RULES source-of-truth domain. A listing whose channel manager owns that domain will refuse the write. See Requests and responses.

Bookings

Scope	Tier	What it allows
reservations:read	standard	Read your bookings and enquiries: dates, party size, status and what was charged.
reservations:write	sensitive	Approve or decline requests to book, and answer guests who asked you to price an add-on.
reservations:cancel	sensitive	Cancel a confirmed booking, which frees the dates and may refund the guest under your cancellation policy.
reservations:refund	restricted	Send a refund on a booking, and change the amount a booking is charged.

reservations:read

Read your bookings and enquiries: dates, party size, status and what was charged.

Grants:

• The booking list and each booking’s detail, by reference code
• Type and origin (HAVEN, or the channel manager that owns it)
• Dates, whole nights, and party size: guests, children, infants, pets
• The pricing snapshot in integer minor units with a sibling currency code, or null where none was persisted
• confirmedAt, cancelledAt and the cancellation reason
• The host’s own note on a block
• A summary of the listing the booking is on

Does not grant:

• The guest’s name or email address — both are returned as null without guests:read
• The guest’s phone number, which is not on this surface at any scope
• The message thread on the booking — see messaging:read
• Card details, Stripe identifiers or identity-verification documents, none of which are on this surface at any scope
• Approving, cancelling, refunding or repricing anything

reservations:write

Approve or decline requests to book, and answer guests who asked you to price an add-on.

Approving a request charges the guest and confirms the stay on your calendar.

Grants:

• approve_booking
• respond_bundle_quote

Does not grant:

• Cancelling a confirmed booking — see reservations:cancel
• Refunding one or changing what it is charged — see reservations:refund
• Creating a booking directly, which is not on the v1 surface
• Reading the bookings it approves — see reservations:read

Writes target the RESERVATIONS source-of-truth domain. A listing whose channel manager owns that domain will refuse the write. See Requests and responses.

reservations:cancel

Cancel a confirmed booking, which frees the dates and may refund the guest under your cancellation policy.

This cannot be undone, and it emails your guest.

Grants:

• cancel_reservation

Does not grant:

• Issuing a refund outside the cancellation policy — see reservations:refund
• Approving or repricing a booking
• Blocking the dates it freed — see calendar:write

Writes target the RESERVATIONS source-of-truth domain. A listing whose channel manager owns that domain will refuse the write. See Requests and responses.

reservations:refund

Send a refund on a booking, and change the amount a booking is charged.

This moves money out of your account. Every call is confirmed in two steps before anything is charged or refunded.

Grants:

• issue_booking_refund and adjust_booking_price, both of which declare confirmation: 'required' and are only reachable through propose then commit

Does not grant:

• Payouts to your bank, your Stripe Connect account, or your Haven subscription — none of those are grantable at any tier
• Any charge not attached to one of your bookings
• Cancelling a booking — see reservations:cancel

Writes target the RESERVATIONS source-of-truth domain. A listing whose channel manager owns that domain will refuse the write. See Requests and responses.

Discount codes

Scope	Tier	What it allows
discounts:read	standard	Read your discount codes, what they take off, and what they apply to.
discounts:write	standard	Change, enable, disable and delete your discount codes.

discounts:read

Read your discount codes, what they take off, and what they apply to.

Grants:

• Every discount code on the account, its redeemable string, percentage, date window and enabled state
• The listing or collection reference code it applies to

Does not grant:

• Redemption history or revenue attribution, which are not on the v1 surface
• Validating a code against a specific stay
• Creating or changing a code — see discounts:write

discounts:write

Change, enable, disable and delete your discount codes.

Grants:

• update_discount_code, toggle_discount_code, delete_discount_code

Does not grant:

• Creating a discount code. The action takes a nested target: { scope, propertyId | propertyGroupId }, and the shared raw-id refusal scans top-level keys only, so today the only working call path is the raw integer id that refusal cannot see. Creation lands once the nested translator does; a public operation name is permanent, so it is not shipped broken first
• Setting a fixed-amount discount, which the model does not carry

Writes target the RATES source-of-truth domain. A listing whose channel manager owns that domain will refuse the write. See Requests and responses.

Guidebook

Scope	Tier	What it allows
guidebook:read	standard	Read the non-secret parts of your guidebooks: house rules, checkout steps, contact details, and how check-in works.
guidebook:secrets:read	restricted	See the wifi password, gate code, directions and check-in instructions for your listings.

guidebook:read

Read the non-secret parts of your guidebooks: house rules, checkout steps, contact details, and how check-in works.

Grants:

• Check-in and check-out times, and whether check-in is flexible
• checkInMethod — the word "keypad" or "lockbox", never the code itself
• Pet rules prose, checkout instructions and the checkout checklist flags
• The listing’s contact email and phone number

Does not grant:

• The wifi network name and password, gate code, directions, check-in instructions or check-in photos — all six string fields come back empty and the photo array comes back empty without guidebook:secrets:read
• The guidebook PIN (Property.guideAccessPin), which is a credential and is never returned at any scope
• Smart-lock access codes, which are encrypted at rest and are not on this surface at any scope
• Writing any guidebook field — no v1 scope writes the guidebook

guidebook:secrets:read

See the wifi password, gate code, directions and check-in instructions for your listings.

These are the details a stranger would need to get inside. Only grant this to an app that has to deliver them to your guests.

Grants:

• Exactly the fields in PUBLIC_FIELD_GATES['guidebook:secrets:read'], which is asserted equal to LOCKED_GUIDE_STRING_FIELDS plus checkInPhotos, read from src/lib/guide-access/locked-guide-fields.ts at test time so the two can never diverge

Does not grant:

• Smart-lock access codes (EventAccessCode.encryptedCode), which are not on the public surface at any scope
• The guidebook PIN, which is a credential
• Writing any of these values — no v1 scope does
• The guidebook itself: this scope only unlocks fields inside a payload guidebook:read returned, which is why it must be requested alongside it

Must be requested alongside: guidebook:read.

Messages

Scope	Tier	What it allows
messaging:read	sensitive	Read your guest message threads and the messages in them.
messaging:send	sensitive	Send messages to your guests, from you.
messaging:write	standard	Clear the unread badge on your message threads.

messaging:read

Read your guest message threads and the messages in them.

Message bodies are correspondence between you and your guests.

Grants:

• The thread list: kind, the booking and listing each thread belongs to, last message time, a 200-character preview, which side sent it, and whether it is unread
• Each message: sender, source (Haven, a channel manager, SMS, WhatsApp, email), body, attachment count, delivery status and timestamp

Does not grant:

• Sending anything — see messaging:send
• Clearing the unread badge — see messaging:write
• The guest’s name or email on a thread — see guests:read
• Attachment bytes, which this surface counts but does not carry

messaging:send

Send messages to your guests, from you.

Messages reach a real person by email, SMS or WhatsApp and cannot be recalled.

Grants:

• send_host_message, into an existing thread addressed by conversation code

Does not grant:

• Reading the thread it is writing into — see messaging:read
• Starting a thread with anyone who is not already a party to one of your bookings or enquiries
• Marketing sends, broadcasts, or messaging a guest after their stay is archived
• Bypassing the per-thread throttle, which is enforced independently of the token’s own rate-limit budget

messaging:write

Clear the unread badge on your message threads.

Grants:

• mark_conversation_read

Does not grant:

• Sending anything — see messaging:send. Split from it deliberately, so an inbox mirror can keep your badge honest without gaining the ability to write to a guest
• Deleting a thread or a message
• Marking a GUEST’s side of a thread read, which is a different command on a different principal and is not on this surface

Guests

Scope	Tier	What it allows
guests:read	sensitive	See guest names and email addresses on your bookings and message threads.

guests:read

See guest names and email addresses on your bookings and message threads.

This shares your guests’ personal details with a third party.

Grants:

• guestDisplayName and guestEmail on a booking’s detail
• guestDisplayName on a booking in a list
• guestDisplayName on a message thread
• Nothing else — the exact field list is PUBLIC_FIELD_GATES['guests:read'], and a test asserts the projection reads that table rather than an inline list

Does not grant:

• Any booking or thread the token could not already see: this permission only fills in fields on records another permission returned, which is why it must be requested alongside reservations:read
• Guest phone numbers, which are not on the v1 surface at any scope
• Payment instruments or identity-verification documents
• Exporting a guest list, or any guest not attached to one of your bookings or enquiries
• Message bodies — see messaging:read

Must be requested alongside: reservations:read.

Sync settings

Scope	Tier	What it allows
integrations:read	standard	See which channel manager or property manager owns each listing, and which parts of it Haven will not let anyone else change.

integrations:read

See which channel manager or property manager owns each listing, and which parts of it Haven will not let anyone else change.

Grants:

• Whether a listing is synced, and the display name of the partner that owns it
• lockedDomains and writableDomains for the listing
• Whether the listing follows a master in a linked calendar group, and that master’s title

Does not grant:

• The credentials for those connections
• Connecting or disconnecting a channel manager
• Changing which domains are locked, or unlocking a field
• Any other app’s grants on this account

Platform

Scope	Tier	What it allows
webhooks:manage	standard	Register and manage the addresses this app uses to be told when something changes.

webhooks:manage

Register and manage the addresses this app uses to be told when something changes.

Grants:

• Creating, listing, updating and deleting this app’s own webhook endpoints for this grant
• Sending a test event, reading the delivery log, and replaying a failed delivery

Does not grant:

• Any other app’s endpoints, or endpoints on any other account
• The app’s CLIENT-WIDE endpoint — the one whose grantId is null, which receives events for every host the app is connected to. A host access token may only ever touch endpoints whose grantId is its own grant; client-wide endpoints are managed from the developer console with client credentials. Without that rule this scope is a confused deputy: one host consenting would let the app repoint, disable, or read the delivery log of a channel carrying every other host’s events.
• The contents of the events themselves, which stay gated by the data scopes: a webhook body carries reference codes and a timestamp, and the follow-up read is what needs reservations:read or calendar:read
• Subscribing to an event class the grant holds no read scope for

Planned scopes

These are real and specified, but not built. Requesting one returns invalid_scope naming the release it is planned for, so you can build a roadmap against it rather than filing a ticket to ask.

Scope	Planned for	Why it is not in v1
payouts:read	v1.2	The payout ledger has no positive-allowlist DTO and reaches Stripe Connect balance data that needs its own redaction pass. Declared now so a partner can plan against it.
reviews:read	v1.2	Haven-native and channel-imported reviews have no reconciled shape yet, and one of the two carries private text that is a secret on a par with a gate code.
reviews:write	v1.2	Blocked on reviews:read.
tasks:read	v1.2	The cleaning and turnover surface is mid-build and its rows are not yet addressed by reference code, so exposing them would publish integer primary keys.
tasks:write	v1.2	Blocked on tasks:read.
media:write	v1.1	Photo upload needs a signed-upload endpoint and a scan step, neither of which exists. Reordering and deleting existing photos rides on listings:write today.
listings:create	v1.2	Creating a listing changes what the account is billed for, so it needs a host-side confirmation the consent screen cannot give in advance.

Scopes no application will hold

Declared so the boundary is documented rather than merely absent. An absent scope is indistinguishable from an oversight; a refused one is a decision. Requesting any of these returns invalid_scope with the reason below.

Scope	Category	Why
billing:read	money	Subscription plan, invoices and card details. canManageBilling() returns false for every partner grant unconditionally, so there is nothing behind this scope to read.
billing:write	money	Starting, changing or cancelling a paid plan spends the host’s money on a decision only the host can make.
payouts:write	money	Moves the host’s money to a bank account. No third party gets this, at any tier, ever.
ads:read	money	The advertising wallet is a prepaid balance; its reads are one query away from its writes and the surface is not worth splitting for a third party.
ads:write	money	Spends a prepaid balance the host topped up.
team:read	human-consent	Who holds a seat on the account is the account’s own access-control state, not business data. A partner that needs to know who acts for the account gets the effective role on account:read.
team:write	human-consent	Inviting, removing or re-roling a teammate grants and revokes whole-account access, so it stays a deliberate human action — never delegated to an app.
workspaces:write	human-consent	Workspace structure decides what every seat on the account can see. canManageWorkspaces() returns false for every partner grant unconditionally.
account:close	human-consent	Irreversible, cancels billing, and revokes every other grant including this one.
devices:write	different-principal	Push device registration writes the human’s own install row, keyed on their User.id and visible to nobody else. A partner acting for the account is not that human, and these are the only two commands that skip the workspace write backstop for a person.
guests:write	different-principal	The nine guest-scoped commands act on the caller’s OWN stay — signing a rental agreement, answering a poll, inviting a co-guest — and deliberately skip the workspace write backstop because a guest writes nothing the account owns. A host-acting token must never reach them. A guest-side grant would be a different grant type with a different consent flow.