Base64url (URL-safe)

Same engine as the main encoder, but URL-safe by default. - and _ instead of + and /.

The two characters that change

The 62 alphanumeric characters at positions 0–61 are identical in both variants. Only the last two and the padding rule differ.

Where base64url is used

• JWT (JSON Web Tokens). All three parts of every JWT are base64url-encoded. Padding is omitted by spec.
• URL query parameters. Embedding base64 in ?token=... requires URL-safe encoding to avoid double-encoding.
• Cookie values. Cookies allow more characters than URL paths, but base64url avoids any escaping concerns.
• Filenames. Most filesystems accept - and _ but reject /. Standard base64 in a filename breaks anywhere with hierarchical paths.
• Database keys. Some systems use base64url-encoded UUIDs as compact, URL-safe primary key external IDs.

Translating between variants

Two-line conversion in any language:

// Standard → URL-safe
b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");

// URL-safe → Standard
b64url.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - b64url.length % 4) % 4);

The bytes encoded are identical; only the surface alphabet differs. A decoder that handles both should normalize URL-safe to standard before calling atob().

Padding: keep it or strip it?

Padding (=) makes the length a multiple of 4. RFC 4648 §5 says it's optional for the URL-safe variant — and JWT explicitly requires it omitted. Other systems may insist on it.

Convention: strip for JWT and URLs, keep for everything else unless told otherwise. Most decoders accept both.

Common pitfalls

• Mixing variants in one pipeline. If you encode standard but decode URL-safe (or vice versa) without normalizing, the value won't roundtrip.
• URL-encoding base64url. If a downstream tool URL-encodes a base64url string anyway, you'll see %2D for -. Disable the URL-encoding step or use standard base64 + URL encode.
• Padding length on URL-safe input. If the input is missing padding, decoders need to add it before calling atob: += until length is multiple of 4.