Tenancy Module (sandloom_tenancy)¶

Tenancy is an optional module managing multi-tenant organizational structure: organizations (tenant roots), membership with roles (owner / admin / member), and invitations (create / accept / revoke). It exposes a cross-module membership read contract so other modules (e.g. billing) can resolve membership and roles without importing tenancy internals, and a critical claims contributor that puts the user's organization ids (tenant_ids) into access tokens.

Domain entities¶

Service contract: tenancy.membership.v1¶

The sanctioned cross-module access path — consumers call core.get_service("tenancy.membership.v1") rather than importing tenancy. The registered object is the read-only MembershipReadContract; the write side (add / change role / remove) is not reachable by other modules or RPC callers.

membership = core.get_service("tenancy.membership.v1")
role = await membership.get_role(org_id, user_id)   # no session argument

Methods take no session: each call runs in tenancy's own read-only Unit of Work on tenancy's database, identically in-process and over internal RPC (SERVICE_BINDINGS). A caller still passing a session gets a DeprecationWarning and the session is ignored.

tenancy.claims.v1 (auto-registered, critical=True) contributes tenant_ids; if tenancy cannot answer, token issuance fails with 503 instead of minting a token without the allowlist.

HTTP API¶

Non-members get 404 on org-scoped routes (no existence leak); a member below the required role gets 403.

Rules API clients must know¶

• New memberships need a fresh access token. After creating an organization or accepting an invitation, call POST /auth/refresh with your current refresh token and replace both stored tokens with the returned pair. Existing access tokens retain their earlier tenant_ids claim; selecting the new organization with X-Tenant-Id on a tenant-scoped application route returns 403 even though the membership exists. Tenancy's own membership endpoints check membership live and do not all require refreshed claims. Logging in again also mints current claims. See the first access-token walkthrough.
• PATCH /api/v1/orgs/{org_id} accepts only name; any other field (including is_active) is rejected with 422. Deactivation is the owner-only DELETE, which soft-deletes the org, publishes tenancy.organization_deleted.v1 and revokes every member's access tokens (immediately, see below).
• Roles — only the owner may change or remove an admin. The owner role is never assigned through PATCH .../members/... (409); use ownership transfer. A role change revokes the member's access tokens (a no-op change revokes nobody). Roles are read live today, so this is not needed for correctness yet; it ends the stale session and keeps a future membership cache / role claims safe. UX: the member's next request answers 401 "Token has been revoked"; the client refreshes (or logs in) and continues under the new role.
• Leaving — any member may leave with DELETE .../members/{own user id}; the owner cannot leave or be removed (409) and must transfer ownership first. Removal and leaving revoke the user's access tokens, so a stale tenant_ids claim stops working immediately (the client refreshes).
• Immediate revocation — removal, leaving, role change, ownership transfer and organization deletion revoke with require_immediate=True: the mark is written BEFORE the change commits, or the change is refused with 503 (cache unreachable) and rolls back. A committed change therefore always rejects the old tokens on the next request, in every service. A request whose guards passed before the change committed still completes (authorization is fresh when the guards run — the TOCTOU window is one in-flight request).
• Ownership transfer — the org row is locked and the actor re-verified as the current owner; the new owner must already be a member (409 otherwise). The previous owner becomes admin. Two tenancy.member_role_changed.v1 events are published (new owner → owner, previous owner → admin), and BOTH parties' tokens are revoked — the owner who made the transfer re-authenticates and continues as admin.
• Invitations — POST .../invitations returns the raw token once (InvitationTokenOut.token) and e-mails the accept link through the notifier capability after the request; a second open invitation for the same email is 409. POST /api/v1/invitations/accept requires the access token's email claim to match the invited address and email_verified: true (403 otherwise); an invalid / expired / used token or a deleted organization is 404; already being a member is 409. Acceptance is single-use and atomic: a failed attempt consumes nothing.

Bounded lists and retries¶

Organization and member lists default to 100 rows, with limit capped at 500. Use the returned X-Next-Cursor to continue. Pending invitations accept limit (default 100, maximum 500) and skip; responses are ordered by creation time and ID.

Send an Idempotency-Key on organization/member/invitation mutations to replay successful retries. Keys are optional for compatibility; when supplied, cache failures refuse the operation. Invitation retries with the same key replay the original raw token rather than losing it to a duplicate-pending conflict. The creation email is awaited by an on-commit callback, after the invitation is durable. This replay cache does not make arbitrary effects exactly once.

TENANT_CLAIMS_MAX_ORGANIZATIONS defaults to 128. Claim issuance and the membership-ID read contract refuse an oversized list rather than silently truncating authorized tenants or minting an unbounded token. Increase the setting deliberately, taking proxy/header limits into account.

Published events¶

tenancy.organization_created.v1    # {organization_id, actor_id?}
tenancy.organization_updated.v1
tenancy.organization_deleted.v1
tenancy.member_added.v1            # {organization_id, user_id, role?, actor_id?, version?}
tenancy.member_removed.v1
tenancy.member_role_changed.v1
tenancy.member_added.v2            # {tenant_id, organization_id, user_id, role?, actor_id?, version}
tenancy.member_removed.v2          # dual-published with v1; version required,
tenancy.member_role_changed.v2     # so a Projection consumes them directly
tenancy.invitation_created.v1      # {organization_id, invitation_id, role?, actor_id?}
tenancy.invitation_accepted.v1
tenancy.invitation_revoked.v1

Invitation events carry no email: the email property stays in the v1 schema as deprecated (never emitted); resolve the invitee via invitation_id.

Audit actions¶

tenancy.member.role_changed, tenancy.member.removed, tenancy.member.left, tenancy.organization.ownership_transferred, tenancy.organization.deleted, tenancy.invitation.created, tenancy.invitation.revoked, tenancy.invitation.accepted.

Capabilities & configuration¶

• Requires: database, eventbus. Descriptor: required=False.
• No tenancy-specific env vars; uses the default database + eventbus instances and the notifier for invitation e-mails (best-effort; the link is {FRONTEND_URL}/invitations/accept#token=<token> — the token is a URL fragment so it stays out of server logs).

Integration with multi-tenancy¶

Tenancy provides the organizational model; the framework's tenant scoping (TenantScoped / TenantScope) provides the fail-closed data isolation. They are complementary — tenancy is the who, tenant scoping is the enforcement. The JWT tenant_ids allowlist may lag membership changes only if the revocation store is unreachable; checks that must observe a removal with certainty use the live contract (has_role_at_least / is_member, or the shared OrgRole atom).

Platform owner directory¶

The optional owner console uses dedicated platform-admin APIs (live session check), separate from organization self-service: GET /api/v1/platform/tenancy/organizations (global, including inactive organizations; bounded offset paging and q, is_active, owner_id filters), GET /organizations/{record_id}, and GET /members (bounded paging, organization_id / user_id filters). Identity must be a successful claims source and the subject must hold the global admin role. Organization ownership does not grant these APIs, and using them never creates membership. See operator guide.