Base64 URL Safe Encoding: What It Is and Why It Matters

What Is Base64 URL-Safe Encoding?

Base64 URL-safe encoding (also called Base64url) is a variant of standard Base64 that replaces characters that have special meanings in URLs and filenames with safe alternatives. Standard Base64 uses + and / as part of its 64-character alphabet, plus = for padding, and all three are problematic in URLs, query strings, and file paths.

Base64url solves this with two simple substitutions:

| Standard Base64 | URL-Safe Base64 | |-----------------|-----------------| | + (plus) | - (minus) | | / (slash) | _ (underscore) | | = (padding) | omitted (usually) |

Why Standard Base64 Breaks URLs

When a Base64-encoded string containing + or / appears in a URL, browser and server behavior becomes unpredictable.

The + Problem

In URL query strings, the + character is interpreted as a space. This behavior comes from the application/x-www-form-urlencoded specification and causes decoded data to contain unexpected spaces.

For example, a Base64 string like Pj4+Pz8/Pw== contains + characters. If this appears in a URL parameter ?token=Pj4+Pz8/Pw==, the server will see ?token=Pj4 Pz8/Pw== — the + becomes a space.

The / Problem

In URL paths, the / character is a path separator. A Base64 string like ab/CD+Ef== contains a / that will be interpreted as a directory level. If this appears in a URL segment, both the client and server may misinterpret the structure.

The = Problem

The = character is used for key-value pairs in query strings. A trailing = in ?data=SGVsbG8= could be ambiguous — is the = part of the Base64 padding or the query parameter syntax?

While percent-encoding can fix these issues (+ becomes %2B, / becomes %2F), it inflates the string length and makes debugging harder. Base64url is a cleaner solution.

How Base64url Works

Base64url is formally defined in RFC 4648 Section 5. It uses the exact same algorithm as standard Base64 — 3 bytes become 4 characters — but with the one-character substitution at positions 62 and 63 of the alphabet:

• Alphabet index 62: + → - (minus)
• Alphabet index 63: / → _ (underscore)

Padding (=) is typically stripped, since it can be inferred from the string length when decoding. A Base64url string is always a valid URL component without additional escaping.

Before and After

Here is what the same binary data looks like in both formats:

Standard:  Pj4+Pz8/Pw==
URL-safe:  Pj4-Pz8_Pw

Where Base64url Is Used

JSON Web Tokens (JWT)

JWT is the most prominent user of Base64url. Every JWT consists of three parts — header, payload, and signature — each URL-safe Base64-encoded and separated by dots:

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNqP0m2iTgCjD0

Notice the dashes and underscores — no plus signs or slashes. If JWT used standard Base64, tokens would break when passed as URL parameters, which is the most common way they are used in web applications.

OAuth and OpenID Connect

Both OAuth 2.0 and OpenID Connect rely on JWT for access tokens and ID tokens, making Base64url encoding fundamental to modern authentication. The authorization code flow, implicit flow, and client credentials flow all transmit tokens that use Base64url.

Web APIs and Query Parameters

Many REST and GraphQL APIs accept Base64-encoded data in query parameters for pagination cursors, filters, or encoded payloads. Base64url ensures these parameters work correctly without additional URL encoding.

Real-world example — API cursor pagination:

GET /api/users?cursor=MjAyNC0wMS0xNVQxMDozMDowMFo

GitHub's API uses this exact pattern for paginating large result sets.

Filenames and File Storage

Base64url strings make safe filenames because they contain no path separators (/), no special characters that confuse filesystems, and no characters that are invalid on Windows (:, *, ?, etc.).

Content Delivery Networks and Cache Keys

CDNs and caching layers often use Base64url-encoded values as cache keys. Standard Base64 with / would create fake directory hierarchies in the cache namespace, leading to ambiguous keys.

Converting Between Standard Base64 and Base64url

Converting between the two variants is straightforward in any language:

JavaScript

// Standard Base64 to URL-safe Base64
function base64ToBase64url(base64) {
  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

// URL-safe Base64 to Standard Base64
function base64urlToBase64(base64url) {
  let result = base64url.replace(/-/g, '+').replace(/_/g, '/');
  // Restore padding
  while (result.length % 4) {
    result += '=';
  }
  return result;
}

Node.js

Node.js provides native Base64url support since version 15.7.0:

// Encode to Base64url
const encodedUrl = Buffer.from('Hello, world!').toString('base64url');
console.log(encodedUrl);
// Output: SGVsbG8sIHdvcmxkIQ

// Decode from Base64url
const decoded = Buffer.from(encodedUrl, 'base64url').toString('utf-8');
console.log(decoded);
// Output: Hello, world!

Python

import base64

# Encode to Base64url
encoded = base64.urlsafe_b64encode(b"Hello, world!")
print(encoded.decode())
# Output: SGVsbG8sIHdvcmxkIQ==

# Decode from Base64url
decoded = base64.urlsafe_b64decode(encoded)
print(decoded.decode())
# Output: Hello, world!

When to Use Standard Base64 vs Base64url

Use Standard Base64 When:

• Encoding email attachments (MIME standard requires it)
• Generating data URLs for HTML/CSS embedding
• Storing data in databases where URL safety is irrelevant
• Interacting with legacy systems that expect standard Base64

Use Base64url When:

• Creating or parsing JWT tokens
• Passing encoded data in URL query parameters or path segments
• Generating filenames from binary data
• Creating cache keys or identifiers
• Working with OAuth tokens or OpenID Connect

Try Base64 URL-Safe Encoding Online

Use our free online Base64 encoder and decoder to convert between standard Base64 and URL-safe Base64 formats. Paste your data, choose your variant, and get the result instantly.