Active company and membership
The active company identifies the context for company-scoped operations. An Auth user can have separate people records in several companies. Company selection uses the accepted token and current live memberships. A stored account preference affects future token issuance, not the company of an already accepted request.
Membership and company resolution
Section titled “Membership and company resolution”The API calls resolve_actor_memberships during
authentication. The service-only RPC uses the
same live actor projection as SQL helpers and the token hook. It includes current
company/person identity, staff/worker flags and capabilities, excluding inactive
or deleted people/companies and invalid, revoked or inactive role grants.
The API and SQL select only the accepted JWT’s
app_metadata.active_tenant_id, validated against the caller’s live membership.
Invalid, foreign or absent selection produces no active company. There is no
top-level claim, stored-preference or first-membership fallback for that request.
/me can return memberships without a selection; a tenant-bound operation’s
active_tenant(user) helper then raises 400.
The browser adopts /me’s verified selection. When exactly one verified membership
exists without selection, its auto-switch path can persist that target and refresh
the session. It does not expose the sole company as selected before verification.
API and database context
Section titled “API and database context”| Consumer | Company source | When it changes |
|---|---|---|
| Privileged API | Accepted token’s app-metadata selection, validated against live memberships | New token for a different selection; live eligibility checked per request |
| Direct database request | The same claim through current_tenant_id(), validated by the live actor projection |
New token for a different selection; current database authority still applies |
| Browser application identity | /me result associated with the current user and exact access token |
Refetched after authentication/token changes |
The token hook validates the stored preference while minting a token. At that
point only, it can choose the first eligible membership sorted by company display
name and identity when the preference is unavailable. It emits no role capability
or platform-authority snapshot that replaces current database checks. Hook
failure emits empty memberships, no selected company and token_hook_error.
The selected trusted tenants.is_platform flag and a live platform:admin grant
outside impersonation determine the common administrator exception. Editable
company type is classification, not authority. These shared actor rules do not
make every API and RLS resource policy
identical.
Explicit company switch
Section titled “Explicit company switch”switchTenant(fkTenant) performs the following sequence:
- Require an existing browser session and clear cached signed file URLs.
- Send
POST /api/supabase-auth/switch-tenantwith the requestedfk_tenantand the current bearer token. - The API verifies the caller and requires that company in its rebuilt membership list. A foreign or inactive membership is excluded from that list; an unlisted target receives 403 before the preference update.
- The API merges the new preference into the Auth user’s stored
app_metadataand returns an acknowledgement. Other metadata keys are retained. - If the account is still current, the browser refreshes the session so the token hook can issue claims for the new preference.
- The browser calls
/meagain and adopts an identity verified for the refreshed token. If the signed-in account changed, the old operation cannot publish it.
sequenceDiagram participant UI as Browser provider participant API as Toolora API participant Auth as Supabase Auth participant Hook as Token hook UI->>API: POST /switch-tenant with target and bearer API->>API: Verify caller and target membership API->>Auth: Merge stored active company preference API-->>UI: Acknowledge preference update UI->>UI: Check the account is still current UI->>Auth: Refresh session Auth->>Hook: Build claims from memberships and preference Hook-->>Auth: Company claims or hook error Auth-->>UI: Refreshed session and token UI->>API: GET /me with refreshed token API-->>UI: Rebuilt identity and resolved company UI->>UI: Commit for this token and derive query context
Cache and permission state
Section titled “Cache and permission state”The provider exposes verified membership data only for the current user and exact access token. During re-verification it withholds previous permissions. Its operation guard instead follows the account so ordinary token rotation does not cancel a legitimate refresh.
AppQueryProvider creates a new TanStack Query client whenever the exposed
activeTenantId changes, including a temporary change to null. Query keys also
include the company ID. Explicit switch and sign-out helpers clear the signed-URL
cache. These are client-state controls; they do not replace filters, RLS or
resource authorization.
The reviewed code does not establish cancellation or rollback of every in-flight
request or mutation when the client changes.
Transition and failure boundaries
Section titled “Transition and failure boundaries”A switch is a sequence, not one transaction across Auth, the database and the
browser. The API acknowledgement confirms the preference write, not completion of
token refresh or browser identity verification. A subsequent refresh failure does
not undo that preference. The browser adopts the company returned by verified
/me; it does not compare that value with the originally requested target.
The preference is stored per Auth user, not per browser tab. A token for Company A continues to select Company A on both API and SQL after the stored preference changes to Company B, provided A’s membership remains live. A refreshed token carrying B selects B. Removing or disabling A’s live membership instead invalidates that selection; neither path silently chooses another company.
This avoids the former same-token API/SQL preference split. It does not establish atomic cross-tab switching, cancellation of every in-flight operation or recall of previously issued signed file URLs. The November 17 release receipt records its specific same-token API/PostgREST checks; it is not exhaustive concurrency proof.
Record scope
Section titled “Record scope”| Record scope | Relevant distinction |
|---|---|
| Company-scoped operational records | Use the selected company, the record’s ownership and applicable policy |
| Relationship-scoped records | Access follows a relationship; a shared party identity does not reveal another company’s private profile |
| Shared identities and catalogues | Their policy is specific to the table or operation; do not invent a tenant column or assume company-wide access |
A company membership, customer-contact relationship, project assignment and portal grant have different meanings. The complete portal and role matrices remain separate topics.
Verification sources and limits
Section titled “Verification sources and limits”The actor/context update is source-reviewed at the revision above. The November 17 release receipt records publication and its named API/PostgREST checks. The table below describes earlier focused documentation checks, not new executions of unchanged tests.
| Evidence | Coverage and execution |
|---|---|
AuthProvider.lifecycle.test.tsx |
Executed: token-bound permissions, ordinary refresh and avoiding refresh after account sign-out |
AuthProvider.sessionRace.test.tsx |
Executed: stale initial/identity results and auto-switch completion after sign-out |
test_auth_context_extraction.py |
Executed: selected identity and missing-company/capability gates with synthetic clients |
test_supabase_auth.py::test_switch_tenant_rejects_unknown |
Inspected; requires the local integration stack and was not executed here |
| Token hook, SQL context helper, query-client replacement and signed-URL clearing | Inspected source; this delivery did not execute database or cache-cancellation scenarios |
The focused results are recorded in PR #648. No shared-company login or provider write was needed for this documentation review.