Skip to content

Toolora uses Supabase Auth to establish a browser session. The application then requests a verified identity from GET /api/supabase-auth/me. That identity supplies company memberships, capabilities and platform-administrator status. The browser uses the API result for application permissions; a saved session alone does not establish those permissions.

The Supabase client enables session persistence, automatic token refresh and session detection in return URLs. SupabaseAuthProvider loads the initial session with getSession() and subscribes to authentication events. Password, magic-link and password-recovery helpers use the SDK. Their complete delivery and return-link workflows are outside this article.

For an authenticated session, the provider calls /me with its access token. It repeats identity verification when the session or token changes. The returned identity is associated with both the user ID and the exact access token used for that request. This association is a client-side stale-result guard. The accepted token also selects the server request’s company; current membership and capabilities remain live database decisions.

sequenceDiagram
participant Browser
participant SDK as Supabase Auth client
participant API as Toolora API
participant Auth as Supabase Auth
participant DB as Application database
Browser->>SDK: Load session or receive authentication event
SDK-->>Browser: Session and access token
Browser->>API: GET /me with bearer
API->>API: Apply configured token checks
API->>Auth: get_user(token)
Auth-->>API: Auth user or rejection
API->>DB: Read active memberships and roles
DB-->>API: Current authorization records
API-->>Browser: Verified identity and resolved company
Browser->>Browser: Commit only for the current user and token
A browser session obtains an API-verified identity before application permissions become available.

require_authenticated extracts a case-insensitive Bearer authorization header and passes the token to _verify_jwt. The verifier performs these steps:

  1. Parse the JWT header and apply the accepted signing-algorithm rules.
  2. Verify supported asymmetric tokens locally when the configured Auth key set is available. Reject invalid signatures, expired tokens, an unexpected audience or an unknown published key ID.
  3. Call Auth’s get_user(token) for every token that passes the preceding stage. Reject an exception or a response without a user.
  4. Resolve claims from the verified payload, or decode the accepted token after Auth has validated it, and require its subject to match the returned user.
  5. Rebuild company memberships and capabilities from application records and resolve the active company.

Successful verification creates AuthedUser. The dependency also records verified user/company identity on request state for later middleware consumers. Authentication is followed by the operation’s capability and resource checks.

Token or key condition API behaviour
HS256 Delegates cryptographic validation to Auth; does not fetch symmetric signing material
ES256 or RS256, published matching key Checks the signature, required exp and sub, and aud=authenticated through the JWT library, then calls Auth
Unsupported algorithm, missing asymmetric kid or known-set mismatch Rejects before calling Auth
No successful key-set fetch yet Leaves the asymmetric verification decision to Auth
Refresh fails after keys were cached Retains the last successful key set; an unrecognized key is still refused

The key set comes from the configured Supabase URL’s Auth JWKS endpoint. Its cache uses a five-minute freshness interval and a thirty-second minimum interval for unknown-key refreshes. This describes the reviewed verifier configuration, not an observation of the running issuer’s current signing algorithm.

The verifier calls the service-only resolve_actor_memberships RPC. It uses the same live people, company and role projection as SQL authorization and token issuance: inactive or deleted people/companies, revoked grants and inactive roles/capabilities are excluded. Role grants must belong to the person’s company.

Only the accepted token’s app_metadata.active_tenant_id selects the current company, and only when a live membership still exists. Stored Auth metadata is a preference for the next issued token, not a fallback for this request. Platform-administrator status requires the selected operator-owned platform company, platform:admin and no impersonation. Ordinary company classification is not platform authority. See company context.

The browser does not supply capability authority. Current role data can change a later permission check without a token refresh; resource checks remain separate.

While a new token is being verified, the provider exposes no previous token’s memberships or administrator status and reports a loading state. Late answers for a replaced token or signed-out account cannot republish their permissions. A refresh operation may continue across ordinary token rotation for the same account, but its permission result remains associated with the token it verified.

If /me fails, the provider exposes no memberships, selected company or administrator status and sets identityUnavailable. The application gate shows an identity-check error. Failure is not evidence that the account has no memberships. The gate also handles token_hook_error separately. A verified sole membership with no selected company can trigger an explicit preference update and token refresh; it is not an unverified browser permission fallback.

Condition Result at the reviewed boundary
Missing or wrong authorization scheme API 401, Missing bearer token
Rejected token, Auth exception or subject mismatch API 401
Auth returns no user API 401, No user for token
Verified user without an active membership /me can return an empty membership list and no active company
Company-required operation without a resolved company Shared active-company helper raises 400
Membership lookup or payload failure No universal 401 mapping; inspect the failing operation

Project-specific portal provisioning can trigger a session refresh when it creates new membership. That additional flow does not replace the identity checks above; its grant rules remain in the customer-portal topic.

The reviewed API calls Auth’s user endpoint. It does not directly correlate the JWT’s session_id with auth.sessions. Neither source comments nor the mocked checks establish immediate rejection of every already-issued token after logout. Supabase distinguishes session removal from access-token lifetime in its session documentation. Runtime configuration and an explicit Auth scenario are needed for a stronger revocation claim.

Evidence Coverage
backend/tests/test_supabase_jwt_verification.py Signing paths, audience, expiry, key rotation/failure and subject disagreement with an Auth double
backend/tests/test_auth_context_extraction.py Missing bearer, invalid/no-user responses, shared dependency identity and selected authorization gates
frontend/src/lib/AuthProvider.lifecycle.test.tsx Token/account association, ordinary refresh and stale results
frontend/src/lib/AuthProvider.sessionRace.test.tsx Initial-load, verification and auto-switch completion after sign-out/account replacement

These focused files were executed for this documentation delivery; results and the checked candidate are recorded in PR #648. They use synthetic or mocked services. They do not exercise a deployed Auth server, delivered magic links or a complete login flow.