SecureStartKit
SecurityFeaturesPricingDocsBlogChangelog
Sign inBuy Now
Home/Glossary/JWT
Authentication

JWT(JSON Web Token)

Also known as: JSON Web Token, access token

Definition

A JWT is a signed, base64url-encoded token carrying claims about a user. Supabase issues JWTs after authentication, signs them with ES256 asymmetric keys (default for new projects since October 2025), and Next.js apps validate them server-side via getClaims without a network round trip to the auth server.

What is a JWT?

A JSON Web Token is a three-part string: header, payload, and signature, separated by dots and base64url-encoded. The payload carries claims like sub (user ID), exp (expiry), and Supabase-specific claims like aal (MFA state) and role.

The signature is the cryptographic guarantee. Anyone can read the claims, but only the auth server (with the private key) can produce a valid signature. Any tampering invalidates the token.

How is a Supabase JWT validated?

Server-side via getClaims(), which fetches the project's public key from the JWKS endpoint (cached locally), then verifies the signature with the Web Crypto API. No HTTP request to Supabase Auth is needed per validation. The older getSession() method reads the cookie without re-validating the signature and should never be used for authorization.

Where should a JWT live in a Next.js app?

In httpOnly cookies, written by @supabase/ssr. Never in localStorage, which is readable by any inline script and turns an XSS bug into a session-theft incident.

Learn more

  • Supabase JWT + Session Management in Next.js
  • Free JWT Decoder

Related terms

  • AALAAL (Authenticator Assurance Level) is a JWT claim that reflects how strongly the user authenticated. AAL1 means one factor (password, OAuth, magic link). AAL2 means a second factor verified for this session (TOTP code). RLS policies read `auth.jwt() ->> 'aal'` to gate sensitive operations.
  • getClaimsgetClaims is the Supabase Auth method that locally validates a JWT against the cached public key from the project's JWKS endpoint and returns the parsed claims. It replaces getSession for authorization because getSession reads the cookie without re-validating the signature.
  • @supabase/ssr@supabase/ssr is the official Supabase package for server-side authentication in Next.js, SvelteKit, and other SSR frameworks. It manages JWT storage in httpOnly cookies, handles the OAuth and magic-link callback cookie writes, and exposes createServerClient and createBrowserClient helpers for each context.
  • Custom Access Token HookA 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().
← Back to full glossary