Développeurs

Scopes

Every endpoint declares the scope it needs. Scopes are named resource:action and there is no implicit hierarchy — properties:write does not include properties:read, so a workspace owner can read the granted list literally.

The vocabulary

Scope	Grants
`properties:read`	Read properties, including amenities, photos metadata and base pricing.
`properties:write`	Create, update and archive properties. Hard deletion is never exposed.
`reservations:read`	Read reservations: dates, status, channel and amounts. Excludes guest identity.
`reservations:guest_read`	Read guest identity (name, email, phone). Every access is audited.
`blocks:read`	Read availability blocks (owner stays, maintenance).
`blocks:write`	Create blocks, and update or delete only the blocks this integration created itself.
`calendar:read`	Read the daily calendar: price, minimum stay, CTA/CTD rules and availability.
`calendar:write`	Update nightly prices and stay restrictions. Changes propagate to the connected OTAs.
`webhooks:manage`	Manage this integration’s own webhook endpoints. Grants no additional data access.

Why you might be missing one

Your effective scopes are the intersection of three independent layers:

Code
what Noé approved for your integration
  ∩ what this workspace consented to share
  ∩ what this specific key was given

Each layer can only narrow the one before it. So being approved for calendar:write does not mean you have it everywhere — a workspace may have shared read access only, or issued you a read-only key for one of their systems.

Call GET /v1/me to see what you actually hold for a given key. It is much faster than inferring it from 403 responses.

There is also a fourth, separate dimension: a grant can be restricted to a subset of properties. When it is, everything outside that subset simply does not exist for you — a request for one of those properties returns 404, exactly as it would for an id that was never real. That is intentional, so the response cannot be used to discover what you were not given.

Sensitive scopes

reservations:guest_read exposes personal data, so it behaves differently:

It is never pre-selected when a workspace authorises you. They have to tick it deliberately.
Every read through it writes an audit record — which reservations, by whom, when. The record contains ids only, never the personal data itself.
Without it, the guest object is absent from the response rather than null, and the request still returns 200. Do not treat a missing guest as an error; treat it as "not shared with you".


Code
{
  "id": "…",
  "object": "reservation",
  "check_in": "2026-09-12",
  "guest": { "first_name": "Camille", "last_name": "Roux", "email": "…", "phone": "…" }
}

When scopes change

A workspace widening your access records a fresh consent. Narrowing it takes effect on your very next request — there is no cache and no token lifetime to wait out, so handle a scope disappearing gracefully rather than assuming what worked yesterday still works.

Authentication

The vocabulary

Scope

Grants

properties:read

Read properties, including amenities, photos metadata and base pricing.

properties:write

Create, update and archive properties. Hard deletion is never exposed.

reservations:read

Read reservations: dates, status, channel and amounts. Excludes guest identity.

reservations:guest_read

Read guest identity (name, email, phone). Every access is audited.

blocks:read

Read availability blocks (owner stays, maintenance).

blocks:write

Create blocks, and update or delete only the blocks this integration created itself.

calendar:read

Read the daily calendar: price, minimum stay, CTA/CTD rules and availability.

calendar:write

Update nightly prices and stay restrictions. Changes propagate to the connected OTAs.

webhooks:manage

Manage this integration’s own webhook endpoints. Grants no additional data access.

Why you might be missing one

Your effective scopes are the intersection of three independent layers:

Code

what Noé approved for your integration
  ∩ what this workspace consented to share
  ∩ what this specific key was given

Call GET /v1/me to see what you actually hold for a given key. It is much faster than inferring it from 403 responses.

Sensitive scopes

reservations:guest_read exposes personal data, so it behaves differently:

It is never pre-selected when a workspace authorises you. They have to tick it deliberately.

Every read through it writes an audit record — which reservations, by whom, when. The record contains ids only, never the personal data itself.

Without it, the guest object is absent from the response rather than null, and the request still returns 200. Do not treat a missing guest as an error; treat it as "not shared with you".

Code

{
  "id": "…",
  "object": "reservation",
  "check_in": "2026-09-12",
  "guest": { "first_name": "Camille", "last_name": "Roux", "email": "…", "phone": "…" }
}