URL Encode Base64: Why base64url Exists

What breaks

+ in a query string is decoded as a space by most servers, so a + inside your Base64 silently becomes a space and the value no longer decodes. / is a path separator and confuses proxies and routers. = is the key-value separator.

This is why a token that works in a JSON body fails when moved into a URL — same bytes, different context.

base64url

RFC 4648 defines a URL-safe alphabet: - replaces +, _ replaces /, and padding is usually dropped. Everything else is identical, and converting is two character replacements:

// standard -> base64url
const toUrl = (b64) => b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

// base64url -> standard (restore padding)
const fromUrl = (s) => {
  const b64 = s.replace(/-/g, '+').replace(/_/g, '/');
  return b64.padEnd(b64.length + ((4 - (b64.length % 4)) % 4), '=');
};

This is what JWTs use for every segment, which is why pasting a JWT part into a standard Base64 decoder fails.

Or percent-encode instead

If you cannot change the encoding — the value comes from a system you do not control — percent-encode the standard Base64 as an ordinary value: + becomes %2B, / becomes %2F, = becomes %3D.

encodeURIComponent does this correctly. The result is longer and uglier than base64url, but it survives any URL, and the receiver decodes it as a normal parameter before Base64-decoding.

What does not work is doing nothing and hoping — that is the case that fails intermittently, depending on whether a particular payload happens to contain a +.

Native support

Most languages have base64url built in: base64.urlsafe_b64encode in Python, Base64.getUrlEncoder() in Java, Buffer.from(x).toString("base64url") in Node 16+, Base64Url in .NET 9.

Use those rather than hand-rolled replacement chains — they handle padding consistently, which is where manual implementations usually differ.