Validating jwt authorization header with zod

[bondz]

Now that zod supports template literals, I tried

const headers = z.object({
  authorization: z.templateLiteral(['Bearer ', z.jwt()])
});

However, zod doesn't validate the jwt part

const result = headers.parse({ authorization: 'Bearer not-a-jwt' }) // passes
console.log(result); // { authorization: 'Bearer not-a-jwt' }  🚨 wrong

A workaround is to write

const bearerTokenToJwt = z.codec(
  z.templateLiteral(['Bearer ', z.jwt()]),
  z.jwt(),
  {
    encode: (value) => {
      return `Bearer ${value}`;
    },
    decode: (value) => {
      return value.split(' ')[1];
    },
  }
);

const headers = z.object({
  authorization: bearerTokenToJwt,
});

const { authorization } = headers.parse({
  authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30',
}); // ✅ passes

headers.parse({ authorization: 'Bearer not-a-jwt' }) // fails

I assumed the original template literal version would work, is there something I'm missing about using z.templateLiteral?

[inkeep-ai-assistant[bot]]

The behavior you’re seeing is expected: z.templateLiteral(['Bearer ', z.jwt()]) does not enforce validation of the inner z.jwt() component beyond string concatenation. Template literal schemas in Zod (v4) concatenate the internal regexes of their components, but for string formats like z.jwt(), only the underlying regular expression is enforced—custom validation logic (such as decoding and structural checks for JWTs) is not applied inside template literals(1).

As a result, z.templateLiteral(['Bearer ', z.jwt()]) only checks that the string matches the regex for a JWT after the "Bearer " prefix, but it does not actually parse or validate the JWT structure. This is why 'Bearer not-a-jwt' passes: the regex is not sufficient to catch all invalid JWTs(1).

Your workaround using z.codec and explicit extraction/validation is required for full JWT validation in the authorization header. This approach ensures the JWT parser runs on the token portion, not just a regex match(1).

📚 Sources:

1. Zod v4 LLMs-Full

---

Have another question? Just tag @inkeep.