Developer

When to Use Base64URL Instead of Base64

Published March 12, 2026 · Updated March 15, 2026 · 4 min read

Base64 and Base64URL encode data identically, with two character substitutions that matter only in specific contexts. Knowing which variant to use — and how to check which one a system expects — prevents silent failures where the data looks fine but decoding produces garbage.

Use Base64URL when the data appears in a URL

Standard Base64's +, /, and = characters have structural meaning in URLs. A + in a query string means a space. A / separates path segments. An = separates keys from values. If a Base64 string containing any of these appears in a URL without percent-encoding, the URL parser misinterprets it.

Base64URL replaces these with -, _, and no padding — characters that have no special meaning in URLs. The result can be embedded directly:

# Standard Base64 — breaks in a URL query string
?token=abc+def/ghi==
# URL parser sees: space, path separator, empty value

# Base64URL — safe in a URL query string
?token=abc-def_ghi
# URL parser sees: one token parameter with value abc-def_ghi

Use Base64URL for JWTs and OAuth tokens

JWT is defined to use Base64URL encoding. The specification is explicit: if you encode a JWT component with standard Base64 and then try to verify the signature, it will fail — the signature was computed over the Base64URL-encoded bytes, not the standard Base64-encoded bytes. They produce different strings, and a mismatch between encoded header/payload and the expected signature means verification always fails.

Similarly, OAuth 2.0 PKCE code challenges are specified as Base64URL with no padding. Using standard Base64 encoding breaks the PKCE flow.

Use Base64URL for filenames

/ is invalid in file and directory names on Unix/Linux/macOS systems — it's interpreted as a path separator. A Base64 string containing / used as a filename either creates nested directories or causes an error. Base64URL's _ replacement is safe in filenames on all operating systems.

Use standard Base64 for everything else

Standard Base64 is appropriate when the encoded data doesn't appear in a URL, filename, or HTTP header: MIME email attachments, data URIs embedded in HTML (data:image/png;base64,... uses standard Base64), and any binary-to-text encoding where the result stays within a text field that doesn't have URL parsing applied to it.

Checking which encoding a system uses: look at the encoded string. Standard Base64 may contain +, /, and trailing =. Base64URL contains - and _ instead, with no padding. If you feed the wrong variant to a decoder, the output is wrong — it won't produce an obvious error, just incorrect data.

Converting between them

Converting from standard Base64 to Base64URL: replace + with -, replace / with _, strip trailing =. Converting from Base64URL to standard Base64: replace - with +, replace _ with /, re-add padding to make the length a multiple of 4.

This conversion is reversible and lossless — both encodings represent the same binary data. The choice of which to use is determined by where the encoded string will be used, not by what it contains.