Supabase's server-framework docs (Next.js middleware, SvelteKit hooks, etc.) defaulted to supabase.auth.getUser() and getSession(), and it was unclear when to use supabase.auth.getClaims() instead. getUser() adds an extra call to the auth server on every request, getSession() just reads the session from storage, and getClaims() was introduced to make server auth faster and safer — but the docs did not explain the distinction. A 30-comment thread with the docs team resulted in an official plan to rewrite all framework docs to convert getSession uses, discourage it, and add guidance docs explaining each method.

Use supabase.auth.getClaims() for fast session validation on the server — it checks local JWT validation (signature and expiration) without contacting the auth server, so use it to protect pages and routes and before interacting with the Data API. Use supabase.auth.getUser() when you need the freshest user record from the auth server: sensitive operations (password/email changes), revocation awareness (whether the session was ended server-side, e.g. logout-all), and anywhere stale metadata like email or phone is unacceptable. The succinct maintainer guidance: getClaims is biased towards session validation, getUser is biased towards user record retrieval. Avoid getSession() in server code: it only reads the session from storage without verifying it. One caveat from the thread: getClaims() does not verify with the auth server whether the session is still valid or the user logged out server-side — the only way to be sure a session is still live is getUser(). Source: https://github.com/supabase/supabase/issues/40985