Base64 Encode and Decode

What Base64 does, and why a bare btoa() breaks

Base64 writes arbitrary bytes using only 64 characters that no text channel is likely to mangle: A-Z, a-z, 0-9, + and /. The encoder reads 3 bytes at a time, splits those 24 bits into four groups of 6, and writes each group as one character. Three bytes in, four characters out, which is why the result is about a third longer than the input. When the length is not a multiple of 3, one or two = characters pad the tail so the output divides evenly by 4. RFC 4648 is the specification.

The format exists because many systems were only ever designed to carry text, and mail servers, HTTP headers and JSON string fields all have opinions about control characters, line endings and bytes above 127. That is why Base64 keeps turning up: email attachments, the Authorization: Basic header, data URLs, the three parts of a JWT, PEM certificate blocks, and binary blobs pushed through an API that only speaks JSON.

The naive browser approach fails on the first non-English word you try. btoa() treats each character of a JavaScript string as a single byte, so it throws InvalidCharacterError on anything above U+00FF: Greek, Cyrillic, Japanese, Korean, Chinese and every emoji. Going the other way, atob() hands back raw byte values, and displaying those directly gives the classic mojibake where café comes back as café. This page runs the text through TextEncoder on the way in and TextDecoder on the way out, so the round trip is lossless UTF-8 for anything you can type or paste.

Which Base64 variant the job needs

• Standard, padded (RFC 4648 section 4): the + and / alphabet with trailing =. This is what the tool above produces and what Basic Auth headers, data URLs and most API fields expect.
• URL and filename safe, known as base64url (RFC 4648 section 5): identical except that + becomes - and / becomes _. Use it in query strings, path segments and filenames, where a slash means something else and a plus can be read as a space.
• base64url with no padding: the same alphabet with the = characters dropped. This is what JWTs use for the header, payload and signature, so a JWT part almost never ends in an equals sign.
• MIME Base64 (RFC 2045): standard alphabet broken into lines of at most 76 characters, used in email bodies. PEM blocks use the same idea with 64-character lines. Decoders are expected to ignore the line breaks.
• Base32 and hex: the neighbors in the same RFC. Base32 uses a case-insensitive alphabet and is how authenticator app shared secrets are written. Hex doubles the size but is readable at a glance, which is why hashes are printed that way.
• Not Base64 at all: if you are escaping text for a URL rather than carrying bytes through one, you want percent-encoding from the URL encoder instead.

How to build an HTTP Basic Auth header

1. Leave the mode on Text → Base64.
2. Type the username, a single colon, then the password, with no spaces around the colon. The first colon separates them, so a password may contain colons but a username may not.
3. Press Copy and build the header as Authorization: Basic followed by a space and the encoded value.
4. Check the result by decoding it back. If you generated the value at a shell prompt instead, a trailing newline is the usual culprit behind a header that looks right and still returns 401.

This header is your credentials in plain sight, reversible by anyone who captures the request, so Basic Auth belongs only on HTTPS. Most HTTP clients will assemble it for you, for example curl -u user:password.

How to decode a string you found in a log or a URL

1. Switch the mode to Base64 → Text and paste the string. Surrounding quotes and trailing commas are the most common reasons a paste fails, so trim them first.
2. If the string contains - or _, it is base64url. Replace - with + and _ with / before decoding.
3. If it has dots in it, you are holding a JWT rather than a single Base64 blob. Split on the dots and decode the first two parts separately, or use the JWT decoder, which does the split and the base64url swap for you.
4. If the output is unreadable symbols rather than an error, the bytes were never text: a compressed payload, an image or an encrypted value all decode cleanly and still look like noise.
5. If the result is JSON, paste it into the JSON formatter to see the structure.

Getting the result where it needs to go

The output is one unbroken line, which is what headers, JSON fields and environment variables want. It is shown with soft wrapping, so what looks like several lines is still a single string when you copy it.

• Into JSON: paste it straight into a string value. None of the Base64 characters need escaping, so no backslashes appear.
• Into a URL: standard Base64 is not URL safe. Either percent-encode it, where + becomes %2B, / becomes %2F and = becomes %3D, or switch to the base64url alphabet before you paste.
• Into YAML or a config file: keep it on one line, and turn off any editor setting that hard-wraps long lines, because an inserted newline changes the value.
• iPhone, iPad and Android: press and hold in the target field and tap Paste. If the string is long, check its end, because some fields truncate without saying so.
• Windows and Mac: Ctrl+V and Cmd+V. Pasting into a terminal is where trouble starts, since a shell may treat / and + as part of a pattern, so wrap the value in single quotes.

The same bytes in different languages and runtimes

Every platform has Base64 built in; the differences are in the defaults, namely which alphabet, whether padding is written, whether long output is wrapped, and how strict the decoder is. Browsers give you btoa() and atob(), which work on bytes rather than text, so the UTF-8 conversion is your job:

const b64 = btoa(String.fromCharCode(...new TextEncoder().encode(text)))
const text = new TextDecoder().decode(
  Uint8Array.from(atob(b64), c => c.charCodeAt(0)),
)

Node.js hides the byte handling inside Buffer, and also ships a base64url encoding name that applies the URL safe alphabet and drops padding:

Buffer.from(text, 'utf8').toString('base64')
Buffer.from(b64, 'base64').toString('utf8')
Buffer.from(text, 'utf8').toString('base64url')

Python 3 works on bytes at both ends, so b64encode returns bytes rather than a string. It has a separate URL safe pair, and its decoder ignores unknown characters unless you pass validate=True:

import base64
base64.b64encode(text.encode()).decode()
base64.b64decode(b64, validate=True).decode()
base64.urlsafe_b64encode(text.encode()).decode()

Go makes the choice explicit with four encodings in encoding/base64: StdEncoding and URLEncoding write padding, RawStdEncoding and RawURLEncoding do not. Java splits the same way through Base64.getEncoder(), getUrlEncoder() and getMimeEncoder().

The command line is where the classic mistake lives. echo adds a trailing newline that becomes part of the encoded bytes and produces a credential the server rejects, so reach for printf. GNU coreutils also wraps output at 76 columns unless you turn that off:

printf '%s' 'user:password' | base64 -w 0   # GNU, no line wrapping
printf '%s' 'user:password' | base64        # macOS, no wrapping by default
printf '%s' 'dXNlcjpwYXNz' | base64 -d      # decode

On macOS the tool is the BSD one, which does not take -w; it has long accepted -D for decoding and takes -d on current versions, so run base64 --help before scripting either flag. Databases expose Base64 too, through encode and decode in PostgreSQL and TO_BASE64() and FROM_BASE64() in MySQL; both wrap long output across several lines by default, so a value selected out of a query may need its newlines stripped first.

Limits, privacy and honest caveats

What leaves your browser: nothing. The conversion runs locally with TextEncoder, TextDecoder and the built-in btoa() and atob(). Nothing you type is uploaded, stored or logged, and the result block is masked against session recording. Even so, prefer a local command for production secrets: a live credential pasted into any web page has been somewhere it did not need to be.

Base64 is not security, and not compression. There is no key, so it offers no confidentiality, and no checksum, so an altered string usually still decodes to something. Reading a JWT payload tells you what the token claims, not whether the claim is true; only checking the signature does that. Encoding also adds about a third to the size, and an image inlined as a data URL cannot be cached on its own and may be refused outright by a strict Content Security Policy.

What this decoder accepts. The browser applies the forgiving-base64 algorithm from the WHATWG Infra standard, which strips ASCII whitespace first, so a MIME-wrapped block keeps its line breaks and still decodes, as does a string whose padding was removed. It rejects the base64url alphabet, since - and _ are not standard Base64 characters, and any length that leaves a remainder of 1 when divided by 4.

Size and accessibility. The whole string is converted in one pass, so a few megabytes of text will make the tab stutter; for anything file-sized, use the command line above. The output is ordinary selectable text in a monospace block rather than an image, so a screen reader can read it and you can select it by hand instead of using the copy button.