Base64 encoder and decoder.

Encoding and decoding Base64

Base64 exists for one reason: to move binary data through channels that only accept text. Email, JSON, XML, HTTP headers and data URLs all break if given raw bytes, so the bytes are mapped onto 64 printable characters first and mapped back at the other end.

1. Pick a direction. Encode takes text or a file and produces Base64. Decode takes Base64 and gives you back the original text or bytes.
2. Choose the alphabet. Standard Base64 uses + and /. Turn on URL-safe and those become - and _, which is what you need for query strings, filenames and JWT payloads.
3. Decide on line breaks. MIME and older email systems require a line break every 76 characters. JSON, most APIs and anything compared with === want a single unbroken string.
4. Copy or swap. Swap takes the output and puts it back in the input with the direction reversed, which is the fastest way to check that a round trip is lossless.

When this comes up

• Debugging a JWT. The three dot-separated parts are Base64url. Paste the middle one here, switch to URL-safe and decode, and the claims appear as JSON.
• Embedding a small image in CSS or HTML. A data URI saves a request, which matters for icons and one-pixel tracking images. Anything past a few kilobytes is usually a net loss.
• Sending a file to an API that wants JSON. Most APIs that accept attachments take a Base64 string in a field rather than multipart form data.
• Checking a signature. Basic auth headers, webhook signatures and some HMAC schemes are Base64 on the wire, and decoding them is the quickest way to see what was actually signed.

A worked example: what the 33% actually looks like

Base64 turns every three bytes into four characters, so the overhead is fixed at one third — but only once the input is long enough to amortise the padding. Short strings look much worse than the rule suggests:

The photo is the number worth internalising. Encoding it produces 472,876 characters — a string larger than the image itself, which then has to be held in memory as text, copied into JSON, escaped again on the way out, and parsed at the other end. That is why binary upload exists. Use a data URI for an icon measured in kilobytes, not for a photograph measured in megabytes.

Note the Chinese case as well: two characters cost six bytes, not two, because UTF-8 spends three bytes on each. The Base64 is eight characters against what a naive byte-per-character assumption would call three. This is exactly where implementations that call btoa on a raw JavaScript string fall over — the string is not bytes, and the conversion has to happen first.

Padding is the detail that breaks integrations. The = characters exist only to round the output up to a multiple of four, and systems disagree about them: some require the padding, some reject it, and some strip it on the way in and expect you to restore it on the way out. If a decoder refuses a string that looks perfectly valid, counting the characters and checking whether the length is divisible by four takes about five seconds and solves it most of the time.

Where Base64 goes wrong

• Treating it as security. A Base64 string is not hidden, it is only unreadable-looking. Authorization headers carrying Base64 credentials are effectively plaintext to anyone who can see the traffic.
• Mixing the two alphabets. A string with - and _ decoded with the standard alphabet produces garbage or an error. If a decoder rejects input that looks valid, this is the first thing to check.
• Stripping or keeping the padding wrongly. Base64 pads to a multiple of four with =. Some systems require the padding, others reject it. Neither behaviour is wrong; you just have to match the receiver.
• Encoding large files through text. The output is 33 percent larger, so a 10 MB image becomes 13.3 MB of characters, plus whatever memory the string costs in your language. Binary upload is almost always better.

Questions