What Base64URL is
Standard Base64 uses + and /, and ends with =. All three have a special meaning in URLs and file names: + is read as a space, / separates path parts and = separates parameters. Base64URL, defined in RFC 4648 section 5, solves this with two changes: + becomes -, and / becomes _. The = padding is usually left out.
| Standard Base64 | Base64URL | |
|---|---|---|
| Characters 62 and 63 | + and / | - and _ |
| Padding | = always | Usually omitted |
| Safe in a URL or file name | No | Yes |
| Line breaks | Optional (MIME, PEM) | None |
Example
The text ???>>> has bytes that produce the characters / and +:
Standard: Pz8/Pj4+ Base64URL: Pz8_Pj4-
The tool shows both next to each other for your text.
Where Base64URL is used
- JWT (JSON Web Tokens). The header, the payload and the signature are Base64URL without padding. Decode them with Base64URL decode, and build tokens with the JWT encoder.
- URLs. Tokens, identifiers, signed links, password reset codes and state parameters in OAuth and OpenID Connect.
- File names and cookies that must not contain
/or+. - PKCE code challenges and WebAuthn values.
Options
- Input is: Text to encode text as UTF-8 and then make it URL-safe, or Base64 to convert a standard Base64 string.
- Keep = padding. Off by default. A few libraries require the padding, so switch it on for them.
Base64URL in code
// Node.js (15.7 and later)
Buffer.from('???>>>').toString('base64url'); // "Pz8_Pj4-"
// JavaScript (browser)
btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
# Python
import base64
base64.urlsafe_b64encode(b'???>>>').rstrip(b'=')
// PHP
rtrim(strtr(base64_encode($s), '+/', '-_'), '=');
Do not confuse it with URL encoding
Base64URL is a way to write bytes as text that is safe in a URL. URL encoding (percent-encoding) is a different method that keeps readable text readable and writes only unsafe characters as %XX. Base64URL is not encryption either.
See also Base64 encode, Base64URL decode and What is Base64?