Also known as: Auth Hook, access token hook
Definition
A Custom Access Token Hook is a Supabase Auth Hook that runs a Postgres function on every JWT issuance to inject custom claims. Typical uses include adding tenant_id and role claims for multi-tenancy, which then become readable inside RLS policies via auth.jwt().
A Custom Access Token Hook is a SQL function registered with Supabase Auth that runs during every access-token issuance, including the initial sign-in and every refresh-token exchange. The function receives the user record and returns a JSON object of claims that get merged into the JWT payload.
Multi-tenancy: query the user's tenant membership and inject tenant_id and role claims. RBAC: inject the user's role for downstream RLS policies. Audit context: inject a customer tier or feature flag set so the database can scope behavior without an extra round trip.
Performance. RLS policies running on every query cannot afford a per-query lookup of the user's tenant or role. With the claim in the JWT, the policy reads auth.jwt() ->> 'tenant_id' for zero database overhead. Refreshes pick up changed claims because the hook re-runs on every refresh, so role changes propagate within the refresh-token cycle.