Authorization

Every service token is issued for exactly one tenant. The {tenant} segment in every URL must match the tenant the token was issued for — requests to another tenant return 403 Forbidden.

Scopes control which resource families a token may read or write. They are attached to the token when it is provisioned.

• facilities:read — read facilities and rooms
• residents:read — read resident profiles
• residents:write — create or update residents and their activities
• connections:read — read family/staff connections
• webhooks:manage — manage webhook subscriptions

Some resources have row-level permissions on top of scopes (for example, a resident can be restricted to a specific facility). If the token has the right scope but cannot access the specific record, the API still returns 403.

When authorization fails, the API returns:

{
  "status": 403,
  "message": "Forbidden",
  "details": "Token does not have the required scope: residents:write"
}