## The Character Problem
Standard Base64 uses 64 symbols: A-Z, a-z, 0-9, +, and /. Those last two are the problem. In a URL, + means a space and / is a path separator. Drop a standard Base64 string into a query parameter and the server decodes it wrong.
URL-safe Base64 — also called Base64url — replaces + with - and / with _. Same algorithm, different two characters. The output can live in a URL without escaping.
This is not a minor detail. I once spent an afternoon debugging a password-reset link that worked for some users and not others. The link contained a standard Base64 token. Users whose token happened to contain a + or / got broken links because the email client or the browser interpreted those characters as URL syntax. Users whose token contained only letters and digits had no problem. The fix was switching to Base64url. Every link worked after that.
Base64url vs Base64: The Difference
| Character | Standard Base64 | URL-safe Base64 | |-----------|-----------------|-----------------| | 62nd | + | - | | 63rd | / | _ | | Padding | = | often omitted |
That is the entire difference. The encoding logic is identical otherwise. You can convert between them with two string replacements. The output length is the same. The decode is the same. Only the alphabet changes.
Encode Base64 for a URL Parameter
In Node.js, pass the URL-safe flag:
javascript const token = Buffer.from("user:42:expire:1735689600", "utf8") .toString("base64url"); // "dXNlcjo0MjpleHBpcmU6MTczNTY4OTYwMA"
Note: no trailing =. Base64url typically omits padding because = is also a reserved URL character. The decoder re-adds it.
In the browser, there is no built-in base64url, so you do the swap by hand:
javascript function toBase64Url(str) { return btoa(str) .replace(/\+/g, "-") .replace(/\//g, "_") .replace(/=+$/, ""); }
And back:
javascript function fromBase64Url(b64url) { const pad = b64url + "=".repeat((4 - (b64url.length % 4)) % 4); return atob(pad.replace(/-/g, "+").replace(/_/g, "/")); }
The decode function does three things: re-add padding, swap the URL-safe characters back to standard, then decode. Miss any of those steps and you get garbage or an error.
A Real Example: Signed Link
You generate a one-time download link. The token carries the file ID and an expiry, signed so it cannot be tampered with:
text https://example.com/d/dXNlcjo0MjpleHBpcmU6MTczNTY4OTYwMA
Try that with standard Base64 and the / characters split the path. Try it with + and the server reads spaces. URL-safe Base64 keeps the token intact through any router, proxy, or parser. The link works in every email client, every browser, every messaging app.
When You Must Use Base64url
- Tokens in URL paths or query strings. - JWTs. The JWT spec mandates Base64url for all three segments — see decode JWT tokens by hand. - Short-lived signed links. - Any opaque identifier that must survive URL transport.
When Standard Base64 Is Fine
- JSON payloads (no URL parsing involved). - Email attachments, data URIs, config files. - Anywhere the string never touches a URL.
If you are not sure, use Base64url. It costs nothing and avoids a class of bugs that are miserable to debug — a token that works on your machine but breaks in production because a proxy rewrites + to %20. The standard Base64 alphabet is a landmine in URL contexts.
The Padding Question
Standard Base64 pads to a multiple of 4 with =. Base64url usually drops the padding because = is itself a reserved character in URLs. Decoders handle this by re-adding padding before decoding, as in the fromBase64Url function above.
If your library expects padding, keep it. If your transport is a URL, drop it. Just be consistent on both ends. Mixing padded and unpadded Base64url in the same system causes intermittent failures that depend on whether the input length happens to be a multiple of 3.
Common Pitfalls
**Mixed alphabets.** Encoding with standard and decoding with URL-safe (or vice versa) produces garbage whenever the input contains a + or /. Pick one alphabet per system and document it.
**Double encoding.** If you Base64url-encode a string and then URL-encode the result, you get ugly output like dXNlcjo0Mg%3D%3D. You do not need both. Base64url exists precisely so you can skip URL-encoding. If you see %3D in your tokens, you are double-encoding.
**Case sensitivity.** Base64 is case-sensitive. aBc and ABC decode differently. URLs generally preserve case, but some legacy systems uppercase everything. If yours does, Base64 is the wrong tool — you need a case-insensitive encoding like Base32 or hex.
**Inconsistent padding.** Some libraries pad, some do not. If your encoder pads and your decoder does not expect padding, it fails. If your encoder strips and your decoder expects padding, it fails. Standardize.
Quick Reference
- Standard: + and /, padded with =. - URL-safe: - and _, padding often omitted. - Node: Buffer.from(data).toString("base64url"). - Browser: btoa then replace +→-, /→_, strip =. - Decode: reverse the swaps, re-add padding, then atob.
Encode URL-safe strings with the NovelCrypt Base64 encoder. For the JSON context where URL-safety usually does not matter, see Base64 in JSON REST APIs.,