JWT claims

Use verified identity in policies

JWT claims documents the immutable user context available to policies.

Policies must read server-verified identity and claims rather than caller-supplied SQL values.

Use it when a policy depends on subject, role, token, session, email, or custom claims.

Requirements for JWT claims

• Prerequisite — An authenticated project user and a documented claim schema.
• Prerequisite — A policy migration and tests for missing, malformed, and changed claims.
• Required value — Subject/user ID, role, email, session ID, token ID, and bounded custom-claim keys.
• Required value — Expected behavior when a claim is absent or null.

Policy functions

• auth.uid() returns the verified end-user subject.
• auth.role() returns the verified project role.
• auth.claim(name) reads an allowlisted immutable claim value.
• Policy evaluation never trusts a caller-authored SQL function or token payload.

CREATE POLICY tenant_documents ON documents
  FOR SELECT TO authenticated
  USING (
    owner_id = auth.uid()
    OR organization_id = auth.claim('organization_id')
  );

JWT claims workflow

• 1. Define the smallest stable custom-claim schema.
• 2. Reference claims through documented auth functions in policy DDL.
• 3. Issue or refresh a session containing the expected server-owned claims.
• 4. Test allowed and denied rows.
• 5. Invalidate cached scope when claims change.

Verify jwt claims

Policies produce deterministic access from verified claims and clients cannot expand scope by changing SQL parameters.

Troubleshoot jwt claims

• A policy trusts a request parameter as identity — replace it with auth context.
• A changed claim leaves stale offline rows visible — invalidate and resnapshot the scoped replica.

Continue from JWT claims

• Apply row-level policies.
• Review offline cache scope.