Caller authority across application layers
Caller authority combines an accepted identity, current live relationships and permission for the target operation and resource. The token selects the internal request’s company; live SQL projections determine current membership and capabilities. A successful authentication does not by itself authorize a project, invoice or portal action. API route policy applies the resulting authority to a particular operation.
The shared actor foundation prevents the API and RLS from independently interpreting role activity. Detailed predicates belong to authentication, company context and resource permissions.
From token to authorized work
Section titled “From token to authorized work”flowchart TD Token[Incoming bearer] --> Issuer[Issuer and token verification] Issuer --> Auth[GoTrue accepts the same token] Auth --> Actor[Live actor memberships] Actor --> Selected[Accepted token selects internal company] Selected --> Capability[Operation capability or dedicated flow policy] Capability --> Resource[Resource and relationship scope] Resource --> Work[Business read, mutation or provider work]
services/auth_context.py asks the issuer verifier and GoTrue to accept the same token and checks that its subject agrees with the returned account. It then calls the service-only actor RPC. v_live_actor_people, private.actor_people and private.actor_memberships own current person eligibility, membership and active unrevoked grants.
The selected internal tenant comes from the accepted token’s app_metadata.active_tenant_id and must remain in the live membership set. Stored account preference, the first membership and top-level lookalike claims are not fallbacks for that request. /me may return memberships without a selection; tenant-bound business work refuses missing context. An explicit switch mints and verifies a new token.
Responsibility by layer
Section titled “Responsibility by layer”| Layer | Establishes | Does not establish alone |
|---|---|---|
| Auth issuer and GoTrue | Accepted account/token identity | Current authority over a business record |
| Shared live SQL projections | Eligible person/company, role grants and capabilities | Customer publication or a worker assignment |
| Browser verified identity | Current token’s context for controls and queries | A security boundary for direct requests |
| RLS and function policy | Direct client’s permitted rows and changes | Scope of a separate service-role query |
| API capability dependency | Required operation permission before handler work | Ownership/admission of the requested resource |
| Dedicated resource helper/RPC | Target company, person and relationship | All stronger domain operations or external confirmation |
Authorization reads may themselves use the privileged client. The required ordering is authorization reads first, then admitted business work. It is inaccurate to promise that no service-role query occurs before a capability check: authentication and capability resolution need those reads.
Platform authority requires a live grant in the selected tenant whose operator-owned is_platform flag is true, outside impersonation. Editable tenant classification and a role name are insufficient. A platform capability exception still does not remove the route’s resource-scope obligation.
Portal authority and token changes
Section titled “Portal authority and token changes”Customer project authority is derived from exact live non-worker company/person pairs and customer or direct-project relationships. That resource company can differ from the internal selected workspace. Worker assignment and UE commitment policies are separate models. Customer access owns the stronger rules for customer-wide recipient changes and completion.
The browser’s AuthProvider binds verified identity to both account and exact access token. While a rotated token is unverified, it withholds the previous token’s authority. Late answers for an old token cannot replace the newer result; ordinary refresh operations can continue for the same account without treating every token rotation as an account switch.
Example and scoped evidence
Section titled “Example and scoped evidence”A synthetic user switches from Company A to B while A’s /me response is delayed. The browser must not expose A’s permissions under B’s token. An already accepted A token still selects A for its own request; changing account preference does not silently reinterpret it as B.
The AuthProvider lifecycle tests specify delayed-response and token-change cases. The actor database suite and local GoTrue/PostgREST tests address the shared API/RLS contract with actual tokens. Source inspection of those tests is distinct from execution or shared business verification; current receipts belong in the PR.