RequiredClaims missing properties

[dcroote]

Bug report

• I confirm this is a bug with Supabase, not with my own application.
• I confirm I have searched the Docs, GitHub Discussions, and Discord.

Describe the bug

The docs list claims that are "always present in Supabase JWTs". While some like iss and sub are present in the RequiredClaims object, email, phone, and is_anonymous are not (see below). This interferes with type checking e.g. of claims.email within the object returned by supabase.auth.getClaims().

auth-js/src/lib/types.ts

Lines 1273 to 1286 in 420930e

	export type RequiredClaims = {
	iss: string
	sub: string
	aud: string | string[]
	exp: number
	iat: number
	role: string
	aal: AuthenticatorAssuranceLevels
	session_id: string
	}
	export type JwtPayload = RequiredClaims & {
	[key: string]: any
	}

To Reproduce

See above.

Expected behavior

All required claims listed in the docs are present.

Screenshots

N/A

System information

N/A

Additional context

N/A

[masda70]

Workaround for missing claims types

Edit: Updated to show a better approach with proper type extension.

This is indeed a typing issue. The claims object contains these properties at runtime, just missing from the type definitions. Here's a workaround using a proper type extension:

import { SupabaseClient, RequiredClaims, AMREntry, UserAppMetadata, UserMetadata } from '@supabase/supabase-js'

type UserJwtClaims = RequiredClaims & {
  email?: string
  phone?: string
  is_anonymous?: boolean
  app_metadata: UserAppMetadata
  user_metadata: UserMetadata
  amr: AMREntry[]
}

async function getUserJwtClaims(
  supabase: SupabaseClient
): Promise<UserJwtClaims | null> {
  const {
    data: claimsData,
  } = await supabase.auth.getClaims()

  if (!claimsData?.claims) {
    return null
  }

  return claimsData.claims as UserJwtClaims
}

This approach extends RequiredClaims with the missing properties that are actually present in the JWT claims at runtime, providing better type safety than casting to User while waiting for the official types to be updated.

[masda70]

Update: Fixed my mistake in my previous comment - use proper type extension instead of casting to User.

For additional context, this type mismatch becomes particularly apparent when working with JWT claims vs the full User object (which we obtain using the familiar getUser method). The User interface contains many database-specific properties that aren't present in JWT claims:

Properties in User but NOT in JWT claims:

• id (JWT claims use sub instead)
• User entity timestamps: created_at, updated_at, confirmed_at, last_sign_in_at
• Temporary state fields: new_email, new_phone, action_link
• Multi-identity and 2FA: identities[], factors[]
• Database-only flags: is_sso_user, deleted_at

Properties in BOTH User and JWT claims but missing from RequiredClaims:

• email ✅ (mentioned by OP)
• phone ✅ (mentioned by OP)
• is_anonymous ✅ (mentioned by OP)
• app_metadata ✅ (user application metadata)
• user_metadata ✅ (custom user data)
• amr ✅ (authentication method references)

[dcroote]

Thanks for the workaround @masda70