← All posts
·7 min read·GuardLayer

"unable to parse or verify signature": Supabase JWT fix

SupabaseAuthJWTSecurity

invalid JWT: unable to parse or verify signature is a 403 from Supabase Auth: the bearer token you sent isn't a JWT this project signed and still accepts. The text after the comma names the cause: a key sent where a token belongs, a signing algorithm or key the project doesn't accept, a token from another project, or an expired token. Fix the token you send. Don't mint your own with the JWT secret.

You'll usually see it as AuthApiError from supabase-js, after auth.getUser() or another Auth call, with error_code: "bad_jwt".

Where does "invalid JWT: unable to parse or verify signature" come from?

It comes from parseJWTClaims in internal/api/auth.go in supabase/auth:

p := jwt.NewParser(jwt.WithValidMethods(config.JWT.ValidMethods))
token, err := p.ParseWithClaims(bearer, &AccessTokenClaims{}, func(token *jwt.Token) (interface{}, error) {
    // look up the key by "kid"; if there's no kid and alg is HS256,
    // fall back to the legacy JWT secret
    ...
    return nil, fmt.Errorf("unrecognized JWT kid %v for algorithm %v", token.Header["kid"], token.Header["alg"])
})
if err != nil {
    return nil, apierrors.NewForbiddenError(apierrors.ErrorCodeBadJWT,
        "invalid JWT: unable to parse or verify signature, %v", err)
}

The %v is the error from the JWT library, so the part after the comma changes with the cause. Only Auth endpoints produce this string. PostgREST rejects bad tokens with its own PGRST301 / JWSError messages, and Edge Functions with a bare Invalid JWT; those have their own posts on the PostgREST JWT errors and Edge Function 401 Invalid JWT.

Read the suffix: what each one means

Suffix after the commaWhat happenedFix
token is malformed: token contains an invalid number of segmentsSomething that isn't a JWT arrived as Authorization: Bearer ...: an sb_publishable_ / sb_secret_ key, an empty string, the text undefinedPut the user's access token in Authorization; API keys go in apikey
token signature is invalid: signing method ES256 is invalidThe token's algorithm isn't in the project's accepted listSign tokens with the keys the project (or local stack) is configured for
token signature is invalid: signature is invalidSigned with a key this project doesn't hold: another project's token, a rotated secret, or a token your own code mintedUse a token issued by this project's Auth
unrecognized JWT kid ... for algorithm ...The token names a signing key (kid) the project doesn't haveSame: the token came from somewhere else, or its key was revoked
token has invalid claims: token is expiredA real token, past its expRefresh the session; see Supabase JWT expired

Two of these are verbatim from real reports. supabase/cli#4524 hit the "invalid number of segments" case when a client built with the new secret key talked to a local stack, which tried to parse the key as a JWT. supabase/cli#4488 got AuthApiError: invalid JWT: unable to parse or verify signature, token signature is invalid: signing method ES256 is invalid after generating ES256 signing keys locally while the local Auth server still accepted only HS256.

The pattern is the same every time: the token didn't come from the Auth server you're talking to, or it came from it too long ago. The commonest real-world version is an environment mix-up, where a staging session cookie or a staging URL ends up next to production keys after a deploy.

How do I decode the token without leaking it?

Decode it locally, not on a website. An access token is a live credential until it expires, and pasting it into an online decoder hands it to a third party. The header and payload are base64url, so one line in your terminal is enough:

node -e 'const [h,p]=process.argv[1].split(".");for (const x of [h,p]) console.log(JSON.parse(Buffer.from(x,"base64url")))' "$TOKEN"

Check three fields. iss should be https://<your-ref>.supabase.co/auth/v1; a different ref means a different project. alg and kid in the header should match a key listed under your project's JWT signing keys. exp is a Unix timestamp: compare it to date +%s.

The fix that hands out every account

When the token "never verifies", some developers stop asking Auth for one and sign their own with the project's JWT secret:

import jwt from "jsonwebtoken";

// "invalid JWT: unable to parse or verify signature" stopped once we
// signed our own token with the project's JWT secret.
export function adminToken(userId: string) {
  return jwt.sign(
    { sub: userId, role: "service_role" },
    "super-secret-jwt-token-with-at-least-32-characters-long",
    { expiresIn: "10y" }
  );
}

That literal is the default JWT secret of the Supabase local stack. It's published in Supabase's own CLI and docs, so if a project ever runs with it, anyone can mint tokens for it. With a real secret the problem is quieter but the same: the legacy JWT secret is a single shared HMAC key. Whoever holds it can sign a token with any sub and any role, which makes them every user and, with role: "service_role", past every RLS policy. A ten-year expiresIn means a leaked token outlives any rotation you'd plan. A hardcoded service_role JWT stays a breach even after you delete it from the repo, because git history keeps it.

It also stops working. Look at the key lookup in the source above: a token without a kid is only checked against the legacy secret when alg is HS256. After the JWT signing keys migration, self-minted tokens fail with exactly this error once the legacy secret is revoked, and the tempting "fix" is to keep the legacy secret alive forever.

How do I fix "unable to parse or verify signature" properly?

Send a token that Auth issued. In practice that means:

  • For a user: pass the session's access_token, which supabase-js and @supabase/ssr already do. If you call Auth with fetch, the user token goes in Authorization: Bearer and your publishable key in apikey.
  • For a server job: don't fake a user. Create a client with the secret key from server-only code. It bypasses RLS by design, so keep it out of anything the browser can reach.
  • For custom claims such as a role or tenant: use the Custom Access Token Hook, so Auth signs them for you. The hook must return claims in the schema Auth expects, or sign-in fails.
  • For local development: generate keys and tokens with the CLI that runs the stack, and keep local keys out of production env files.

What GuardLayer catches, and what it doesn't

GuardLayer doesn't flag the sample above today. Neither the published local secret as a jwt.sign argument nor a role: "service_role" payload is a rule yet, so a scan of that file comes back clean. If the secret sits in an env file committed to the repo, the general secret rules may catch the file, but don't count on a scanner for this one. The grep below is the check.

Quick self-check

# Code that signs its own Supabase tokens
grep -rnE "jwt\.sign|new SignJWT|SUPABASE_JWT_SECRET|JWT_SECRET" --include=*.ts --include=*.tsx --include=*.js .

# The local default secret anywhere outside local config
grep -rn "super-secret-jwt-token-with-at-least-32-characters-long" . --exclude-dir=node_modules

Any hit that signs a payload with role or sub needs to go. If a real JWT secret was ever committed, rotate it and move to signing keys.

FAQ

Why does Supabase say my JWT has an invalid signature when I just got it? Usually because it came from a different project or environment than the URL you're calling. Decode it locally and compare iss with your project ref.

What does "token contains an invalid number of segments" mean in Supabase? The bearer value isn't a JWT at all. A real JWT has three dot-separated parts; an API key, an empty string or undefined doesn't. Send the user's access token in Authorization.

Can I sign my own Supabase JWTs with the JWT secret? You can, and you shouldn't. Anyone holding that secret can impersonate any user or the service role. Use the Custom Access Token Hook for extra claims and the secret API key for server jobs.

Is it safe to paste a Supabase access token into jwt.io? Treat it like a password until it expires. Decode it locally with the one-liner above instead.

Check your Supabase Auth settings and tables, free

Connect your Supabase project read-only. GuardLayer checks your Auth settings (leaked passwords, email confirmation, secure email change, token rotation, CAPTCHA, MFA) and your RLS, policies and grants, and says how to fix each problem. It never reads your rows and can't change anything.

Check my Supabase project

Prefer to check code instead? Scan your repo, no signup.

Keep reading