Configure Custom JWT Claims for Role and Organization Context
The Global Administrator configures Supabase Auth hooks or custom JWT templates to embed role and organization_id claims into the access token. These claims are then consumed by RLS policies across all tables. This is essential for multi-organization isolation — a coordinator at NHF must not see HLF's data, and the JWT claim is the authoritative source for this determination at the database layer.
User Story
Acceptance Criteria
- Given a user authenticates successfully, when the JWT is decoded, then it contains role, organization_id, and local_association_id claims matching the user's database record
- Given a user belongs to multiple organizations, when their JWT is generated, then it includes claims for all applicable organization memberships
- Given a user's role changes in the database, when they refresh their token, then the new JWT reflects the updated role claim within the configured token refresh window
- Given an RLS policy references auth.jwt()->>'organization_id', when a query executes, then the claim is correctly evaluated against the row's organization column
- Given the admin updates the JWT template, when existing sessions make requests, then the old tokens continue working until expiry and new tokens use the updated claim structure
Business Value
Custom JWT claims are the bridge between Supabase Auth and RLS policies. Without them, every database request would require a secondary lookup to determine the user's role and organization — doubling query latency and introducing race conditions. Embedding these in the JWT ensures atomic, consistent access control that scales across all 60+ tables without performance degradation.
Components
- Supabase Client Service service
- Database Schema data
- Supabase Platform infrastructure