The Problem Characters

In URLs, '+' is traditionally used to encode spaces in query strings. The '/' character is the path separator. When Base64-encoded data containing these characters is placed in a URL, parsers may misinterpret them — treating '+' as a space or '/' as starting a new path segment. This corrupts the data.

The URL-Safe Alphabet

Base64 URL encoding (defined in RFC 4648) replaces '+' with '-' and '/' with '_'. Both '-' and '_' are URL-safe characters with no special meaning in URL syntax. The padding character '=' is often also omitted in URL-safe contexts.

Where URL-Safe Base64 Appears

JWT tokens use URL-safe Base64 for all three parts since JWTs appear in URL fragments and HTTP headers. OAuth tokens, signed URL parameters, and any Base64 data embedded in URLs should use the URL-safe variant. Standard Base64 is appropriate for email MIME parts and data URLs.

Decoding URL-Safe Base64

Decoding URL-safe Base64 requires using the URL-safe alphabet or translating '-' back to '+' and '_' back to '/' before passing to a standard decoder. Most modern Base64 libraries accept both variants and handle the conversion automatically.

Key Takeaway

Use URL-safe Base64 (- instead of +, _ instead of /) whenever encoded data will appear in URLs, JWT tokens, or HTTP headers. Use standard Base64 for email MIME parts and data URLs.