Base64URL Explained: Making Base64 Safe for the Web

Base64 is a ubiquitous standard for encoding binary data into ASCII text. However, when developers attempt to pass standard Base64 strings through web environments—specifically inside URLs, query parameters, or file systems—they quickly encounter critical routing errors and broken data.

To solve this fundamental incompatibility, the Internet Engineering Task Force (IETF) introduced a variant known as Base64URL (defined in RFC 4648). In this guide, we will explore why standard Base64 fails on the web, how Base64URL fixes the problem, and where it is commonly used in modern web architecture.

The Problem with Standard Base64 on the Web

To understand the necessity of Base64URL, we must look at the standard Base64 character index. The 64 characters consist of uppercase letters (A-Z), lowercase letters (a-z), numbers (0-9), and two specific symbols: the plus sign (+) and the forward slash (/). Additionally, standard Base64 utilizes the equals sign (=) for padding at the end of the string.

While these characters are safe for email (MIME) and JSON payloads, they hold special semantic meaning within a Uniform Resource Locator (URL):

• Forward Slash (/): In a URL, the forward slash is a reserved structural character used to separate directories or pathways (e.g., example.com/api/v1/users). If a Base64 string containing a slash is placed directly into a URL path, the web server's router will incorrectly interpret it as a directory break, resulting in a 404 Not Found error.
• Plus Sign (+): In the query string portion of a URL (the part after the ?), the plus sign is historically interpreted by many web servers and application frameworks as a space character. If a Base64 string containing a + is passed as a query parameter, the server will replace the + with a space, silently corrupting the encoded data. When you attempt to decode it later, it will fail.
• Equals Sign (=): The equals sign is reserved in URLs to separate a query parameter key from its value (e.g., ?token=value). While appending it to the end of a value is sometimes tolerated by modern parsers, it can cause ambiguity or parsing errors in stricter systems.

The Base64URL Solution

The solution provided by RFC 4648 is elegantly simple. Base64URL creates a "URL and Filename Safe" alphabet by swapping out the two problematic characters for safe alternatives:

1. The Plus Sign (+) (Index 62) is replaced with a Hyphen / Dash (-).
2. The Forward Slash (/) (Index 63) is replaced with an Underscore (_).

Because hyphens and underscores are completely safe and hold no structural meaning in URL routing or query parsing, the resulting encoded string can be passed freely across any web address without the need for additional layers of percent-encoding (URL Encoding).

The Padding Issue

While RFC 4648 defines the character swap, the specification leaves the treatment of the = padding character somewhat open, noting that padding may be omitted if the length of the data is known or can be deduced. In practice, almost all modern implementations of Base64URL—most notably JSON Web Tokens (JWT)—strictly require that the padding characters be completely stripped from the final string.

Because a Base64 decoder can mathematically determine exactly how many padding bytes are missing based on the string's length modulo 4, omitting the padding does not cause data loss and further guarantees that the string will not conflict with URL query parameter parsing.

Converting Between Base64 and Base64URL

Because the underlying math and chunking algorithms are identical, converting a standard Base64 string into a Base64URL string (and vice versa) in a programming language is a trivial string replacement operation.

JavaScript Example (Standard to Base64URL)

function toBase64Url(base64String) {
    return base64String
        .replace(/+/g, '-') // Replace + with -
        .replace(///g, '_') // Replace / with _
        .replace(/=+$/, ''); // Strip trailing =
}

JavaScript Example (Base64URL to Standard)

function fromBase64Url(base64UrlString) {
    let base64 = base64UrlString
        .replace(/-/g, '+') // Replace - with +
        .replace(/_/g, '/'); // Replace _ with /
        
    // Add padding back if necessary
    while (base64.length % 4) {
        base64 += '=';
    }
    
    return base64;
}

Where is Base64URL Used?

Base64URL is the foundation of many modern web security and authentication protocols.

JSON Web Tokens (JWT)

The most widespread use of Base64URL today is in JSON Web Tokens. A JWT consists of a header, a payload, and a signature, separated by dots. Because JWTs are designed to be passed in HTTP Authorization headers and as URL query parameters (for things like password reset links or single sign-on flows), the entire token must be URL safe. Therefore, the JSON header, JSON payload, and binary signature are all strictly encoded using Base64URL with padding omitted.

OAuth and OpenID Connect

Protocols like OAuth 2.0 and OIDC heavily rely on Base64URL to safely pass state tokens, authorization codes, and cryptographically signed nonces through browser redirects (which occur entirely within the URL bar).

WebAuthn (Passkeys)

The modern WebAuthn API, which powers biometric Passkeys, exchanges cryptographic challenges and credential IDs between the browser and the server. Because this data is exchanged via JSON and often tied to web origins, the WebAuthn specification dictates the use of Base64URL for all binary formatting.

Conclusion

While standard Base64 is perfect for email attachments and static Data URLs, it is inherently dangerous to place in web routing structures. Base64URL provides a simple, elegant character substitution that ensures complex binary data can traverse the web safely without triggering 404 errors or query parameter corruption.

If you need to quickly format data, you can use our Online Base64 Encoder to safely translate your text.