JWT Uses Base64URL, Not Standard Base64: Decoding JWT Parts Correctly

JWT (JSON Web Token) is defined in RFC 7519, which specifies that the header, payload, and signature are each encoded with base64url (RFC 4648 §5), not standard base64. The reason is practical: JWTs are designed to be transmitted in URLs, HTTP headers, and query parameters. Standard base64 uses + and / as alphabet characters. In URLs, + is interpreted as a space character (in application/x-www-form-urlencoded encoding), and / is interpreted as a path separator. Using standard base64 in a URL would require additional percent-encoding of those characters, making the token longer and more awkward.

Base64url solves this by substituting two characters: + becomes - and / becomes _. Both - and _ are safe in all URL contexts without percent-encoding. Base64url also omits the = padding character that standard base64 uses to pad output to a multiple of 4 characters. In a JWT, the three parts are separated by periods, so padding would need to be removed before transmission anyway to avoid ambiguity.

The structure of a JWT is header.payload.signature, where each part is independently base64url-encoded. The header and payload are UTF-8 encoded JSON objects, so decoding them yields human-readable JSON. The signature is the HMAC-SHA-256 or RSA-SHA-256 binary digest of the header.payload string, so decoding the signature part yields binary bytes, not JSON. Never attempt to JSON.parse() the third part of a JWT.

This distinction between base64url and standard base64 is the root cause of almost all "atob fails on JWT" bugs. Developers copy a JWT from an Authorization header or localStorage, split on '.', and pass a part directly to atob() or Buffer.from(part, 'base64'). If the part happens to not contain - or _ (many short payloads do not), the code works. But JWTs with longer payloads, especially those with many claims or non-ASCII content, almost certainly contain - or _ in their base64url encoding, causing silent data corruption or an exception.

When atob() throws InvalidCharacterError on a JWT part, examine the JWT part string for - or _ characters. The presence of either confirms it is base64url encoded. Count the characters: standard base64 length is always a multiple of 4 (including = padding). Base64url omits padding, so the length may not be a multiple of 4. The number of missing padding characters is: (4 - length % 4) % 4.

When Buffer.from(part, 'base64') in Node.js produces wrong JSON (SyntaxError in JSON.parse, or unexpected character values in decoded strings), the issue is likely that - or _ in the JWT part are being silently dropped. Node.js's standard 'base64' encoding ignores characters outside the base64 alphabet rather than throwing. This silent failure makes the bug hard to detect because no error is thrown — the code appears to work but produces wrong output.

To quickly identify whether a base64url string's decode failure is due to missing padding or alphabet differences, manually inspect the string length modulo 4. If length % 4 == 1, the string is invalid (a valid base64url-encoded value will never have length % 4 == 1 because the original 3-byte groups produce output lengths of 4, 8, 12, ... or with 1 leftover byte: 2 base64url chars, with 2 leftover bytes: 3 base64url chars). If you encounter a JWT part with length % 4 == 1, the JWT may be malformed or truncated.

For debugging JWT payload content in the browser, open browser devtools console and paste this one-liner: JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(token.split('.')[1].replace(/-/g,'+').replace(/_/g,'/')+'=='.slice(0,(4-token.split('.')[1].length%4)%4)),c=>c.charCodeAt(0)))). This is a useful diagnostic expression for any JWT token.

In Node.js 16 and later, use the 'base64url' encoding with Buffer.from(): Buffer.from(jwtPart, 'base64url').toString('utf8'). This is the cleanest solution — the 'base64url' encoding handles the character substitution and padding restoration internally. For JSON payloads: JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')). This works correctly for all valid JWTs, including those with and without - or _ characters in the part.

In Node.js 14 and earlier, or in any environment without native 'base64url' Buffer support, use the two-step approach: (1) convert the alphabet with .replace(/-/g, '+').replace(/_/g, '/'), and (2) restore padding with base64Str += '=='.slice(0, (4 - base64Str.length % 4) % 4). The expression (4 - len % 4) % 4 correctly computes 0, 1, or 2 padding characters: 0 when no padding is needed (len % 4 == 0), 2 when 2 chars are needed (len % 4 == 2), 1 when 1 char is needed (len % 4 == 3). The case len % 4 == 1 is invalid and should not occur in a well-formed JWT.

In browsers, after the alphabet conversion and padding restoration, use atob() to decode to a Latin1 byte string. If the payload contains only ASCII characters (common for simple JWTs with string claims), JSON.parse(atob(base64Str)) works correctly. For UTF-8 safety (always recommended), convert the atob() output to a Uint8Array and decode with TextDecoder: new TextDecoder().decode(Uint8Array.from(atob(b64), c => c.charCodeAt(0))). This correctly handles non-ASCII characters in JWT claims.

For production code that needs to validate JWTs (not just decode them), use a proper JWT library: jsonwebtoken in Node.js, jose (works in Node.js, browsers, and Deno), or the jwt-decode npm package for decode-only operations. These libraries handle the base64url conversion, signature verification, and claims validation (exp, iss, aud) correctly and are maintained against known vulnerabilities.

The JWT signature (the third part after the second period) is binary data — the HMAC-SHA-256 digest or RSA signature bytes. Decoding it with base64url gives you raw bytes, not JSON. A HMAC-SHA-256 signature is 32 bytes; an RS256 signature is 256 bytes (2048-bit RSA) or 512 bytes (4096-bit RSA). Never attempt to JSON.parse() the third part of a JWT. If you want to inspect the signature, decode it to a Buffer or Uint8Array and display it as hex: Buffer.from(parts[2], 'base64url').toString('hex').

The Bearer prefix in Authorization headers is a frequent source of splitting bugs. The Authorization header value is 'Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0In0.abc'. When you split by '.', you get ['Bearer eyJhbGciOiJIUzI1NiJ9', 'eyJzdWIiOiIxMjM0In0', 'abc'] — the first part includes 'Bearer ' which is not valid base64url. Always strip the 'Bearer ' prefix before splitting: const token = authHeader.replace(/^Bearer /, ''); const parts = token.split('.').

Base64url-encoded JWT parts should never contain whitespace, but some systems add newlines when logging long tokens. If you are reading a JWT from a log file or a copy-pasted string, strip whitespace before processing: token.trim().replace(/\s/g, ''). A single newline character in the middle of a JWT part will cause all base64 decoders to produce incorrect output.

JWT RS256 and ES256 signatures have different binary structures. RS256 uses PKCS#1 RSASSA-PKCS1-v1_5 (a fixed-length signature). ES256 uses ECDSA with P-256 in the JWT-specific DER-to-raw conversion format (two 32-byte integers R and S concatenated, not the ASN.1 DER encoding that OpenSSL produces). If you are verifying an ES256 JWT signature with OpenSSL, you must convert the JWT's 64-byte raw signature to DER format first. The jose library handles this automatically.

Trusting an unverified JWT for authorization decisions is the most critical mistake. Decoding a JWT header and payload is trivial — anyone can create a JWT with any claims without a signature. The signature must be cryptographically verified against the expected secret (HMAC) or public key (RSA, ECDSA) before trusting any claim in the payload. Decoding-only libraries like jwt-decode explicitly do not verify signatures and should never be used for authorization.

Caching the JWT public key verification result incorrectly leads to authentication bypass. If you cache whether a JWT was valid without storing the specific claims, an attacker can replace a valid JWT with a different valid JWT for a different user but reuse the cached validation result. Cache the verified claims object (subject, roles, expiry), not a boolean validity flag.

Ignoring the algorithm field in the JWT header enables algorithm confusion attacks. Some early JWT libraries accepted an alg: 'none' header indicating no signature was required, allowing attackers to forge tokens. Current JOSE libraries default to rejecting 'none'. However, if you use an RS256 key to verify and an attacker creates an HS256 token where the HMAC secret is the RSA public key (which is publicly available), naive libraries that accept both algorithms with the same key will accept the forged token. Always specify the expected algorithm explicitly in your verification call: jwt.verify(token, publicKey, {algorithms: ['RS256']}).

Not checking JWT expiration in microservices is a common oversight. If service A receives and caches a JWT, and the token expires 5 minutes later, service A may continue accepting the cached token without re-verifying expiry. Always check the exp claim in the payload even for cached tokens: if (payload.exp < Date.now() / 1000) throw new Error('Token expired'). The jwt.verify() function checks expiry automatically, but manual claim extraction without a library does not.

For production code that decodes JWTs, use the jose library (available on npm, Deno, and with browser support) or jsonwebtoken for Node.js. These libraries are actively maintained, handle base64url conversion transparently, verify signatures, validate all standard claims (exp, iat, nbf, iss, aud), and are tested against known attack patterns. Implement JWT decoding yourself only for educational purposes or in environments where dependencies are strictly limited.

When you must decode JWT parts manually (debugging, logging, lightweight tooling), encapsulate the base64url decode logic in a single utility function and use it everywhere. A production-quality utility function should: validate the JWT has exactly three parts, use 'base64url' Buffer encoding in Node.js 16+ (falling back to manual replacement in older versions), decode to UTF-8 with TextDecoder in browsers, catch and re-throw JSON.parse errors with context about which JWT part failed, and never attempt to parse the third (signature) part as JSON.

For logging and debugging JWTs in production, log only the payload claims that are safe to expose — avoid logging the full token or the signature. The JWT itself is a credential: anyone with the token can use it until it expires. Log the sub (subject), iat (issued at), exp (expiry), and any role claims, but redact or truncate the full token string. Use a structured logging library that lets you define a log redaction policy for fields that match jwt or authorization.

For JWT inspection in development environments, use the ToolDock JWT Decoder tool to paste a token and immediately see the decoded header and payload with proper base64url decoding, algorithm identification, and expiry display. This is faster than writing debug code and eliminates the manual base64url conversion steps entirely.