Is Base64 URL safe?

Dark navy cover card with the title 'Is Base64 URL safe?' in white and a green accent bar

No, standard Base64 is not URL safe. Its alphabet includes + and /, and it pads with =, and all three characters already have a job inside a URL. The URL-safe variant, base64url, swaps + for - and / for _ and usually drops the padding, so the string can sit in a path or query unchanged.

Why standard Base64 is not URL safe

Standard Base64 is not URL safe because three of its characters are reserved in URLs. The letters and digits pass through untouched, but +, / and = do not.

RFC 4648 gives the 64-character alphabet: A-Z, a-z, 0-9, then + for value 62 and / for value 63, with = as padding. The same document warns that non-alphanumeric characters, "in particular, "/"", "may be problematic in file names and URLs."

The URL side is set by RFC 3986. Its unreserved set, the characters that never need escaping, is letters, digits, hyphen, period, underscore and tilde. +, / and = sit in the reserved set instead. When data would clash with a reserved character's role as a delimiter, the rule is that it "must be percent-encoded before the URI is formed."

What +, / and = do in each part of a URL

Each of the three characters breaks a URL in a different place. The plus sign damages query strings, the slash damages paths, and the equals sign confuses anything that splits on key=value.

I ran one small test in Node.js to see every failure at once. The 4 bytes fb ff bf 3e encode to +/+/Pg== in standard Base64.

Character In a path In a query string
+ Kept as a plus Read back as a space
/ Splits the path into extra segments Usually kept
= Usually kept Clashes with the key=value separator

The plus sign. The URL Standard tells form-style query parsers to "Replace any 0x2B (+) in name and value with 0x20 (SP)." So reading token from https://example.com/verify?token=+/+/Pg== returns " / /Pg==". The reference page for the query-string API shows the same loss with its own Base64 sample. Our post on plus signs decoding as spaces covers that rule in more depth.

The slash. Put the same string in a path, /reset/+/+/Pg==, and the path splits into reset, +, + and Pg==. The router sees four segments where you meant two, so the route that expects one token never matches.

The equals sign. Padding tends to survive. Still, RFC 4648 notes that = "is typically percent-encoded when used in an URI", and hand-rolled parsers that split on every = will cut the value short. Our post on why Base64 ends with an equals sign explains when the padding appears at all.

The failure that gives no error

The worst outcome of unsafe Base64 in a URL is a decoder that returns wrong bytes without complaining.

In my test, the damaged value " / /Pg==" behaved differently in two decoders:

atob(" / /Pg==");
// throws InvalidCharacterError

Buffer.from(" / /Pg==", "base64");
// <Buffer ff f3 e0>, no error

The browser's atob refused the string. Node's Buffer skipped the spaces and returned 3 bytes, ff f3 e0, in place of the original 4. If those bytes were a signature or a reset token, the check would fail and nothing in the logs would say why. Only tokens that happen to contain a + break, so the bug looks random.

How base64url makes Base64 URL safe

base64url makes Base64 URL safe by replacing the two problem characters with unreserved ones. Section 5 of RFC 4648 defines it: - (minus) takes the place of + at value 62, and _ (underline) takes the place of / at value 63.

Hyphen and underscore are both in the unreserved set, so no part of a URL treats them specially. My test bytes become -_-_Pg, which is 6 characters and needs no escaping anywhere.

Padding is the part you still have to check. The swap alone leaves = in place, and libraries disagree on the default.

Node.js drops it for you: the base64url encoding omits padding when it encodes, and also accepts regular Base64 when it decodes. Browsers go the other way. toBase64() takes alphabet: "base64url", but omitPadding defaults to false. In Python, urlsafe_b64encode output "can still contain = if padded is true (default)", and the padded parameter arrived in version 3.15.

JWTs leave no choice. The JWS spec uses the URL-safe set "with all trailing '=' characters omitted".

For the full alphabet comparison and how to convert between the two, see Base64 vs Base64URL.

Percent-encoding standard Base64 instead

Percent-encoding is the other way to put Base64 in a URL: keep the standard alphabet and escape the three unsafe characters. It works in query strings, costs extra length, and is risky in paths.

encodeURIComponent escapes everything except letters, digits and - _ . ! ~ * ' ( ). So + becomes %2B, / becomes %2F and = becomes %3D, 3 characters each. My 8-character sample grows to %2B%2F%2B%2FPg%3D%3D, which is 20 characters. The base64url form was 6.

Paths are where it fails. Apache's AllowEncodedSlashes setting defaults to Off, and with that default, URLs containing %2F in the path "are refused with a 404 (Not found) error." The link is valid and the token is correct, yet the server rejects every token that happens to contain a slash. If you're choosing between the JavaScript escaping functions, our comparison of encodeURI and encodeURIComponent shows which one touches these characters.

Which form to use where

Use base64url without padding for anything that travels in a link, and keep standard Base64 for places that are not URLs.

Where the string goes Use Why
URL path segment base64url, no padding A raw / splits the path and %2F may be refused
Query string value base64url, no padding A raw + reads back as a space
JWT base64url, no padding Required by the spec
File name base64url / is a directory separator
JSON body, HTTP header, data URI Standard Base64 No URL parsing happens there
Third-party API that demands standard Base64 in a query Percent-encode it You don't control the decoder

My take: don't percent-encode Base64 when you own both ends. base64url is shorter, no server setting can break it, and nobody has to remember to escape it.

The limitation: URL safe does not mean private or tamper-proof. Anyone can decode the string, so a base64url user ID in a link is as readable as plain text. Our post on whether Base64 is encryption covers what to use when the value must stay secret.

To check a value quickly, the Base64 encoder on this site has a URL-safe output option and runs in your browser.

FAQ

Which Base64 characters are not URL safe?

The plus sign, the slash and the equals sign. All three are reserved characters in a URL. The letters and digits that make up the rest of the Base64 alphabet are fine anywhere in a link.

Is base64url the same as URL-encoding a Base64 string?

No. base64url is a different alphabet that uses - and _ so nothing needs escaping. URL-encoding keeps standard Base64 and escapes + / = as %2B, %2F and %3D, which makes the string longer.

Do I need to remove the = padding for URLs?

It is the safer choice. RFC 4648 says = is typically percent-encoded in a URI and that you can skip the padding when the data length is known. JWTs always drop it.

Does URL-safe Base64 hide the data?

No. URL-safe only means the characters survive a trip through a link. Anyone can decode the string back to the original bytes, so never treat it as encryption.

Sources