Why Base64 Breaks API Requests — And How to Fix It
Base64 encoding contains characters that break URLs and API requests. This guide explains exactly why it happens and how to fix it permanently.
The problem — Base64 uses URL-unsafe characters
Standard Base64 encoding uses 64 characters: A-Z, a-z, 0-9, plus+ and/with = for padding.
The characters +,/ and= have special meaning in URLs. When a Base64 string is included in a URL without proper encoding these characters corrupt the request.
// Standard Base64 encoded token abc+def/ghi== // In a URL this becomes https://api.example.com/verify?token=abc+def/ghi== // Server receives: // + decoded as a space → "abc def/ghi==" // / interpreted as path separator // = causes issues with some parsers
Base64 vs Base64URL — the solution
Base64URL is a URL-safe variant of Base64. It replaces the problematic characters with URL-safe alternatives.
| Standard Base64 | Base64URL | Reason |
|---|---|---|
| + | - | + means space in URL encoding |
| / | _ | / is path separator in URLs |
| = | (removed) | = causes issues in query strings |
Converting between Base64 and Base64URL
// JavaScript — Base64 to Base64URL
function toBase64URL(base64) {
return base64
.replace(/+/g, '-')
.replace(///g, '_')
.replace(/=/g, '')
}
// JavaScript — Base64URL to Base64
function fromBase64URL(base64url) {
let base64 = base64url
.replace(/-/g, '+')
.replace(/_/g, '/')
// Add padding
while (base64.length % 4) {
base64 += '='
}
return base64
}
// Usage
const token = btoa('user:password') // standard Base64
const urlSafe = toBase64URL(token) // Base64URL for URLsReal world scenarios where this breaks
Email verification links
When you encode a user ID or token as Base64 and include it in an email verification URL the + characters break when the user clicks the link.
// ❌ Wrong — standard Base64 in URL
const token = Buffer.from(userId).toString('base64')
const link = `https://app.com/verify?token=${token}`
// Token contains + and / which break the URL
// ✅ Correct — Base64URL safe
const token = Buffer.from(userId).toString('base64url')
const link = `https://app.com/verify?token=${token}`HTTP Basic Authentication
Basic auth uses standard Base64 — not Base64URL. The encoded credentials go in the Authorization header, not a URL, so standard Base64 is correct here.
// Basic auth — standard Base64 is correct
const credentials = btoa('username:password')
fetch(url, {
headers: {
'Authorization': `Basic ${credentials}`
// Standard Base64 is fine in headers
}
})Encode and decode Base64 instantly
Supports both standard Base64 and URL-safe Base64URL encoding.
Open Base64 Tool →