Skip to main content
Every request authenticates with a bearer token. Four credential types resolve to the same tenant-scoped credential, so every endpoint behaves identically regardless of how you authenticate:
  1. API key (casa_…) — the recommended method for machines, scripts, and MCP clients such as Cursor. Generated in Account settings, scoped to your property group (or pinned to one property at creation). Works on both the REST API and the MCP server.
  2. WorkOS AuthKit session (JWT) — how the Casa web app authenticates. The organization and role come from verified token claims (org_id, role); an X-Organization-Id header, when sent, must match the claim.
  3. MCP OAuth connector — how Claude connects (see MCP server). WorkOS AuthKit is the OAuth authorization server; the token is minted for the /mcp resource. These tokens are read-only, group-scoped, and MCP-only — they are rejected on every /v1/* REST route.
  4. Static token — provisioned out of band for machine access, pinned to a single property.

​
Tenant scope

The default scope is the property group — requests return data across every property in the group. Two things narrow it:
  • X-Property-Id header — drills a single request down to one property. The server verifies the property belongs to your group; anything else is 403.
  • Property-pinned keys — an API key created with a property pin is permanently narrowed to that property and ignores the drill-down header.
Tenant scope is resolved entirely server-side from the credential. There is no way to widen it from the request.

​
Scopes

Endpoints require a specific scope; a credential holding * satisfies every scope. API keys carry the full read surface below except read:integrations — integration and connection metadata stays session-only. For session (JWT) auth, scopes derive from your organization role: owner/admin get full read plus write:integrations; member is read-only. MCP OAuth connector tokens are capped to a fixed read-only set — read:guests, read:reservations, read:transactions, read:consents, read:events, read:reviews, read:loyalty, read:tables — regardless of the user’s role. A valid token missing the required scope returns 403:
No token, an unknown token, or a revoked key returns 401:

​
Revocation timing

API keys and static tokens revoke immediately — the next request fails. Session and MCP OAuth credentials derive org and role from signed token claims, so removing a member or changing a role takes effect within the access-token lifetime (≤ 1 hour) rather than on the next request. For instant lockout of a machine credential, revoke the API key.

​
Quick test

The same key authenticates the MCP server.