Authentication and sessions
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.
Browser session state
Section titled “Browser session state”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
API verification
Section titled “API verification”require_authenticated extracts a case-insensitive Bearer authorization header
and passes the token to _verify_jwt. The verifier performs these steps:
- Parse the JWT header and apply the accepted signing-algorithm rules.
- 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.
- Call Auth’s
get_user(token)for every token that passes the preceding stage. Reject an exception or a response without a user. - 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.
- 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.
Signing paths and key availability
Section titled “Signing paths and key availability”| 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.
Authorization data returned by the API
Section titled “Authorization data returned by the API”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.
Pending and failed identity verification
Section titled “Pending and failed identity verification”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.
Session lifetime and review limits
Section titled “Session lifetime and review limits”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.
Verification sources
Section titled “Verification sources”| 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.