Skip to content

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.

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.

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.

switchTenant(fkTenant) performs the following sequence:

  1. Require an existing browser session and clear cached signed file URLs.
  2. Send POST /api/supabase-auth/switch-tenant with the requested fk_tenant and the current bearer token.
  3. 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.
  4. The API merges the new preference into the Auth user’s stored app_metadata and returns an acknowledgement. Other metadata keys are retained.
  5. If the account is still current, the browser refreshes the session so the token hook can issue claims for the new preference.
  6. The browser calls /me again 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
Company switching persists a preference before refreshing the token and verifying browser identity.

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.

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 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.

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.