Encoding & Transport · Field note
Base64URL padding mistakes that break tokens, PKCE, and signed URLs
Learn how omitted padding and alphabet differences create subtle failures in tokens, PKCE code challenges, and signed URL workflows.
Before you start
Decode a small sample first and confirm whether you are changing representation, changing structure, or actually protecting content.
Base64URL errors feel silly because they are small. They are still expensive because they show up exactly where developers expect a token or challenge string to be copy-paste safe.
A one-character difference in alphabet or padding is enough to turn a valid payload into an invalid one, even when the underlying bytes were right before you “fixed” them.
In brief
What it is: Base64URL is the URL-safe variant of Base64 defined in RFC 4648, usually using - and _ instead of + and /, and often omitting padding.
Why it matters: JWTs, PKCE challenges, and signed URL components rely on byte-exact encodings. Manual normalization easily changes the meaning of the value.
Watch for: Adding or removing = padding blindly can make the string parse while still leaving you with the wrong bytes or the wrong transport form.
Why the alphabet matters
Base64URL exists because + and / are awkward inside URLs and filenames. The safer alphabet is useful, but only if both sides agree about it. When one system expects standard Base64 and the other emits Base64URL, the string may look close enough to tempt manual edits.
That is the trap. Similar-looking strings are not interchangeable representations unless the decoding and re-encoding rules are applied deliberately.
Padding is a protocol choice, not a formatting preference
Some protocols omit padding because the encoded length can be inferred. JWT compact serialization is a familiar example. Other tools expect padding and will refuse to decode until it is restored. The right question is not “which style is prettier?” The right question is “what exact form does this protocol specify at this point in the flow?”
PKCE makes this especially visible because the code verifier, SHA-256 digest, and Base64URL code challenge must line up byte for byte. A “helpful” shell pipeline that adds padding or swaps alphabets at the wrong moment can produce a perfectly readable but invalid challenge.
Debug the bytes, not the cosmetic form
When in doubt, decode to bytes and re-encode using the expected variant from a trusted tool. That gives you a grounded answer instead of another round of string surgery. The fastest way to lose half an hour is to keep editing a token-looking value by hand because each version feels almost right.
- Confirm whether the protocol expects Base64 or Base64URL.
- Confirm whether padding is present, forbidden, or ignored.
- Only compare values after converting them to the same variant.
See it in a small example
Notice: The characters changed and the padding may be omitted. That is not cosmetic; it is part of the transport contract.
standard base64: a+b/c==
base64url: a-b_c
What to verify
- Identify the expected alphabet before editing any characters.
- Treat padding rules as protocol rules, not personal preference.
- Normalize both sides to the same variant before deciding they differ.
Common questions
Can I always add padding back?
You can often add it for local decoding, but that does not mean the transmitted form should include it.
Is Base64URL encryption?
No. It is an encoding for byte-safe transport.