Authentication & keys

Every partner request authenticates with an API key in the Authorization header — no cookies, no OAuth dance, no signatures:

Authorization: Bearer hr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys are created self-service in the agency portal under Partner API (Pro plan, or the Partner API add-on on Grow). The full key is displayed once at creation; the platform stores only its SHA-256 hash. Treat it like a password: environment variable or secret manager, never a repository — and never in browser code, where a key would be handed to every visitor.

Verify a new key with GET /partner/v1/me: it answers with the agency, the key’s scopes and its rate budget.

Scopes

Each key carries an explicit set of scopes. Requests beyond the key’s scopes fail with 403 SCOPE_MISSING — create keys with the minimum your integration needs.

Scope	Grants
read:units	GET /partner/v1/units, GET /partner/v1/units/:slug, MCP list_units
read:availability	GET /partner/v1/availability, MCP get_availability
read:rates	POST /partner/v1/quote, GET /partner/v1/fee-types, MCP quote_stay
read:bookings	GET /partner/v1/bookings, GET /partner/v1/bookings/:id, MCP list_bookings
read:guests	GET /partner/v1/guests, GET /partner/v1/guests/:id — personal data
write:bookings	POST /partner/v1/bookings, POST /partner/v1/bookings/:id/cancel

The four plain read scopes are pre-selected when a key is created. read:guests and write:bookings are not: one exposes other people’s personal data, the other changes the agency’s. Both are ticked deliberately or not at all — and an existing key never gains an ability because a new one was added.

Writes are recorded in the agency’s audit trail with the key as the actor, including refused attempts. The MCP endpoint stays read-only.

Rotation & revocation

• Rotate by creating a second key, deploying it, then revoking the old one — both stay valid in between, so rotation needs no downtime.
• Revoke any key instantly in the portal. Revocation is immediate for new requests and permanent.
• Keys can carry an optional expiry date at creation; expired keys answer 401 like revoked ones.
• The portal shows a last used timestamp per key (minute precision), so a forgotten integration is easy to spot — and a dead key easy to retire.

Error responses

HTTP	code	Meaning
401	UNAUTHORIZED	Missing/malformed header, unknown, revoked or expired key, or the agency account is not active
403	FEATURE_DISABLED	The agency’s plan does not include API access
403	SCOPE_MISSING	Key is valid but lacks the scope; the response names it
429	RATE_LIMITED	Over 60 requests in the rolling minute for this key — respect Retry-After
429	QUOTA_EXCEEDED	The agency’s 50,000 requests for this month are spent (budgets)

{ "code": "SCOPE_MISSING", "title": "This API key lacks the 'read:bookings' scope.", "scope": "read:bookings" }