Base64 Encoding Explained: Complete Guide with Examples

You’ve seen those long, random-looking strings starting with data:image/png;base64, in HTML. You’ve decoded JWT tokens and wondered why they look like gibberish. You’ve needed to send binary data through systems that only accept text.

That’s Base64.

But here’s the problem: most explanations either oversimplify (“it’s just converting data to text”) or overwhelm you with binary mathematics. Neither helps you actually use Base64 effectively in real projects.

This guide is different. You’ll learn what Base64 is, how it actually works under the hood, when to use it (and when not to), and see practical examples you can use immediately. No computer science degree required.

By the end, you’ll understand why Base64 makes files 33% larger, how to embed images directly in CSS, decode authentication tokens, and avoid common security mistakes that could expose your data.

Quick Answer: What is Base64 and When Should You Use It?

Don’t have time for 4,000 words? Here’s the TL;DR:

• What it is: A method to convert binary data (images, files, bytes) into text using only 64 safe characters
• When to use it: Embedding images in HTML/CSS, email attachments, storing binary data in JSON/XML, JWT tokens, Basic authentication headers
• When NOT to use it: For encryption (it’s not secure), for large file transfers (use direct binary), for passwords (use proper hashing)
• Key fact: Base64 increases file size by approximately 33%
• Tools: Use our Encoder/Decoder tool for quick conversions

Still here? Great. Let’s dive deep into how Base64 actually works.

What is Base64?

Base64 is an encoding scheme that converts binary data into a text string using only 64 different characters. These characters are guaranteed to be “safe” across different systems, networks, and protocols.

Think of it like this: Binary data speaks a language some systems don’t understand. Base64 translates it into a simpler language everyone can read.

Why Does Base64 Exist?

The original problem: The internet and email systems were originally designed for text, not binary data. When you tried to send a file or image, the systems would corrupt it because they expected text characters.

The solution: Base64 encodes binary data using only characters that are universally safe:

• Uppercase letters: A-Z (26 characters)
• Lowercase letters: a-z (26 characters)
• Numbers: 0-9 (10 characters)
• Special characters: + and / (2 characters)
• Padding character: = (used to align data)

Total: 64 characters (hence “Base64”)

Real-World Analogy

Imagine you need to send a package internationally, but customs only accepts boxes of a specific size and shape. Base64 is like repackaging your items into those standard boxes. The contents are the same, just packaged differently to get through the system.

Visual Example: Encoding Process

Let’s encode the letter “A” to understand the process:

Original text: A
↓
ASCII value: 65
↓
Binary: 01000001
↓
Split into 6-bit groups: 010000 01
↓
Pad to complete group: 010000 010000 (padding added)
↓
Convert to decimal: 16, 16
↓
Map to Base64 characters: Q, Q
↓
Add padding: QQ==

Result: The letter “A” becomes “QQ==” in Base64.

Don’t worry if this seems complex—you’ll rarely need to do this manually. Tools handle it automatically. But understanding the process helps you debug issues and make better decisions.

How Base64 Encoding Works

Let’s break down the encoding process step by step with clear examples.

The Base64 Character Set

Base64 uses exactly 64 characters to represent data:

Padding character: = (indicates the end of encoded data)

Step-by-Step Encoding Process

Example: Let’s encode “Hello”

Step 1: Convert to binary

H → 01001000
e → 01100101
l → 01101100
l → 01101100
o → 01101111

Step 2: Concatenate all binary

010010000110010101101100011011000110111

Step 3: Split into 6-bit groups

010010 | 000110 | 010101 | 101100 | 011011 | 000110 | 1111
       ↑       ↑       ↑       ↑       ↑       ↑     ↑
      18      6       21      44      27      6     60 (needs padding)

Step 4: Pad the last group
The last group has only 4 bits, so we add 2 zeros to make it 6 bits:

111100 → 60

Step 5: Convert to Base64 characters

18 → S
6  → G
21 → V
44 → s
27 → b
6  → G
60 → 8

Step 6: Add padding
Since we padded with bits, we need to indicate this with = characters:

Result: SGVsbG8=

Verification: The string “Hello” encoded in Base64 is SGVsbG8=

You can test this with our Encoder tool to verify!

Understanding Padding

Padding with = occurs when the input bytes don’t divide evenly into 6-bit groups.

Padding rules:

• No padding: When input bytes divide evenly (e.g., 3 bytes = 24 bits = four 6-bit groups)
• One =: When input has 2 bytes remaining (16 bits)
• Two ==: When input has 1 byte remaining (8 bits)

Examples:

"A"     → QQ==     (heavy padding)
"AB"    → QUI=     (one padding)
"ABC"   → QUJD     (no padding)
"ABCD"  → QUJDRA== (heavy padding again)

Pro tip: If you see invalid padding, your Base64 string may be corrupted. Use our Encoder tool to validate and fix encoding issues.

Common Use Cases for Base64

Now that you understand how Base64 works, let’s explore where you’ll actually use it in real projects.

Use Case 1: Embedding Images in HTML and CSS

The problem: Loading external images requires HTTP requests, which slow down page load times.

The solution: Embed small images directly in HTML or CSS using Base64 data URLs.

Example: Embedding a small icon in HTML

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA
AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO
9TXL0Y4OHwAAAABJRU5ErkJggg==" alt="Red dot">

Example: Embedding a font in CSS

@font-face {
  font-family: 'CustomFont';
  src: url(data:font/woff2;base64,d09GMgABAAAAAAYgAA0AAAAA...) format('woff2');
}

When to use this approach:

• Icons under 5KB
• Critical above-the-fold images
• Fonts for immediate rendering
• Reducing HTTP requests for performance

When NOT to use:

• Large images (increases HTML/CSS file size)
• Images that change frequently
• Images used in multiple places (duplication waste)

Tools to help: Convert images to Base64 with our Image to Base64 converter and optimize the output.

Use Case 2: Email Attachments (MIME)

Email systems were designed for text, not binary files. Base64 solves this.

How email attachments work:

1. Your email client reads the file (PDF, image, etc.)
2. Encodes it in Base64
3. Sends it as text in the email body
4. Recipient’s client decodes Base64 back to original file

MIME email format example:

Content-Type: application/pdf; name="invoice.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="invoice.pdf"

JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQg
MSAwIFIKL1Jlc291cmNlcyAyIDAgUgovQ29udGVudHMgNCAwIFI+PgplbmRv
YmoKNCAwIG9iago8PC9MZW5ndGggNDQ+PgpzdHJlYW0KQlQKL0YxIDI0IFRm
CjEwMCA3MDAgVGQKKEhlbGxvIFdvcmxkKSBUagpFVAplbmRzdHJlYW0KZW5k
...

Key insight: This is completely automatic. You never need to manually Base64 encode email attachments—your email client does it for you.

Use Case 3: Basic Authentication Headers

HTTP Basic Authentication uses Base64 to transmit credentials.

Format:

Authorization: Basic <base64-encoded-credentials>

Example:

// Original credentials
const username = "admin";
const password = "secretpass123";

// Combine with colon
const credentials = username + ":" + password;
// Result: "admin:secretpass123"

// Encode to Base64
const encoded = btoa(credentials);
// Result: "YWRtaW46c2VjcmV0cGFzczEyMw=="

// Full header
const authHeader = "Basic " + encoded;
// Result: "Basic YWRtaW46c2VjcmV0cGFzczEyMw=="

⚠️ Security Warning: Base64 is NOT encryption! Anyone can decode this. Always use HTTPS when sending Basic Auth headers, or use more secure authentication methods like OAuth 2.0 or JWT.

Tools: Test authentication headers with our HTTP Headers Checker and decode tokens with our Encoder tool.

Use Case 4: JSON Web Tokens (JWT)

JWTs consist of three Base64-encoded parts separated by dots.

JWT structure:

<header>.<payload>.<signature>

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Decoding the parts:

Header (part 1):

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload (part 2):

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

Signature (part 3): Cryptographic signature to verify integrity

Tools: Decode and inspect JWTs with our JWT Decoder tool to see the contents without executing code.

Use Case 5: Data URLs for API Responses

APIs sometimes return binary data (like generated images or PDFs) as Base64 strings in JSON.

Example API response:

{
  "status": "success",
  "filename": "report.pdf",
  "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iag...",
  "encoding": "base64",
  "size_bytes": 45632
}

Decoding in JavaScript:

async function downloadFile(apiResponse) {
  // Decode Base64 to binary
  const binaryString = atob(apiResponse.content);

  // Convert to byte array
  const bytes = new Uint8Array(binaryString.length);
  for (let i = 0; i < binaryString.length; i++) {
    bytes[i] = binaryString.charCodeAt(i);
  }

  // Create blob and download
  const blob = new Blob([bytes], { type: 'application/pdf' });
  const url = URL.createObjectURL(blob);

  const a = document.createElement('a');
  a.href = url;
  a.download = apiResponse.filename;
  a.click();
}

When to use: Small to medium files (under 1MB), simple API design, avoiding multipart form handling.

Use Case 6: Storing Binary Data in Databases

Some databases and data formats (like JSON) don’t support binary data directly. Base64 provides a workaround.

Example: Storing user avatars in JSON

{
  "user_id": 12345,
  "username": "johndoe",
  "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
  "avatar_size": 8456
}

Better alternatives for large data:

• Store files on disk or object storage (S3)
• Save only file path/URL in database
• Use database binary/blob types when available

Rule of thumb: Only use Base64 for binary data in databases if files are under 100KB and convenience outweighs efficiency concerns.

How to Encode and Decode Base64

Let’s see practical code examples in different languages.

JavaScript (Browser and Node.js)

Browser encoding/decoding:

// Encode string to Base64
const text = "Hello World!";
const encoded = btoa(text);
console.log(encoded);  // "SGVsbG8gV29ybGQh"

// Decode Base64 to string
const decoded = atob(encoded);
console.log(decoded);  // "Hello World!"

Node.js encoding/decoding:

// Encode string to Base64
const text = "Hello World!";
const encoded = Buffer.from(text).toString('base64');
console.log(encoded);  // "SGVsbG8gV29ybGQh"

// Decode Base64 to string
const decoded = Buffer.from(encoded, 'base64').toString('utf-8');
console.log(decoded);  // "Hello World!"

// Encode binary file
const fs = require('fs');
const fileBuffer = fs.readFileSync('image.png');
const base64Image = fileBuffer.toString('base64');

// Decode and save file
const decodedBuffer = Buffer.from(base64Image, 'base64');
fs.writeFileSync('image-copy.png', decodedBuffer);

Encoding with Unicode support:

// ⚠️ btoa() doesn't handle Unicode well
const unicodeText = "Hello 世界! 🌍";

// Modern approach (browser)
const encoded = btoa(unescape(encodeURIComponent(unicodeText)));

// Or use TextEncoder API
const bytes = new TextEncoder().encode(unicodeText);
const binString = String.fromCharCode(...bytes);
const encoded2 = btoa(binString);

Python

Python 3 encoding/decoding:

import base64

# Encode string to Base64
text = "Hello World!"
encoded = base64.b64encode(text.encode('utf-8'))
print(encoded)  # b'SGVsbG8gV29ybGQh'

# Decode Base64 to string
decoded = base64.b64decode(encoded).decode('utf-8')
print(decoded)  # "Hello World!"

# Encode binary file
with open('image.png', 'rb') as file:
    encoded_image = base64.b64encode(file.read())

# Decode and save file
with open('image-copy.png', 'wb') as file:
    file.write(base64.b64decode(encoded_image))

URL-safe Base64:

import base64

text = "Hello World! Testing + and /"
standard = base64.b64encode(text.encode())
url_safe = base64.urlsafe_b64encode(text.encode())

print(standard)  # May contain + and /
print(url_safe)  # Uses - and _ instead

Command Line

Linux/Mac (base64 command):

# Encode text
echo "Hello World!" | base64
# Output: SGVsbG8gV29ybGQhCg==

# Decode text
echo "SGVsbG8gV29ybGQhCg==" | base64 -d
# Output: Hello World!

# Encode file
base64 image.png > image.txt

# Decode file
base64 -d image.txt > image-copy.png

# Encode without line breaks (for inline use)
base64 -w 0 image.png > image-oneline.txt

Windows PowerShell:

# Encode text
$text = "Hello World!"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($text)
$encoded = [Convert]::ToBase64String($bytes)
Write-Output $encoded

# Decode text
$decoded_bytes = [Convert]::FromBase64String($encoded)
$decoded = [System.Text.Encoding]::UTF8.GetString($decoded_bytes)
Write-Output $decoded

# Encode file
$bytes = [System.IO.File]::ReadAllBytes("image.png")
$encoded = [Convert]::ToBase64String($bytes)
[System.IO.File]::WriteAllText("image.txt", $encoded)

Online Tools

Quick encoding/decoding without code:

• Our Encoder/Decoder tool - Fast, private, client-side only
• Image to Base64 converter - Upload images and get data URLs
• JWT Decoder - Decode JWT tokens and inspect claims

Advantages of online tools:

• No installation required
• Works on any device
• Great for quick tests and debugging
• Our tools process data locally (nothing sent to servers)

Base64 Variants

Not all Base64 is the same. Different variants exist for different use cases.

Standard Base64

Character set: A-Z, a-z, 0-9, +, /, =

Uses:

• Email (MIME)
• Basic authentication
• General data encoding

Example:

"Hello World!" → "SGVsbG8gV29ybGQh"

URL-Safe Base64

Problem: Standard Base64 uses + and /, which have special meaning in URLs.

Solution: Replace problematic characters:

• + becomes -
• / becomes _
• Padding = is often removed

Character set: A-Z, a-z, 0-9, -, _

Example comparison:

Standard:  "Hello?test=123" → "SGVsbG8/dGVzdD0xMjM="
URL-safe:  "Hello?test=123" → "SGVsbG8_dGVzdD0xMjM"

Uses:

• URL parameters
• Filenames
• JSON Web Tokens (JWT)
• Any context where URL encoding would be needed

JavaScript implementation:

function base64UrlEncode(str) {
  return btoa(str)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, ''); // Remove padding
}

function base64UrlDecode(str) {
  // Add padding back
  str = str.replace(/-/g, '+').replace(/_/g, '/');
  while (str.length % 4) {
    str += '=';
  }
  return atob(str);
}

Python implementation:

import base64

# URL-safe encode
encoded = base64.urlsafe_b64encode(b"Hello?test=123")
print(encoded)  # b'SGVsbG8_dGVzdD0xMjM='

# URL-safe decode
decoded = base64.urlsafe_b64decode(encoded)
print(decoded)  # b'Hello?test=123'

Base64 Without Padding

Purpose: Save space by removing trailing = characters.

Trade-off: Decoder must calculate expected padding.

Example:

With padding:    "A" → "QQ=="
Without padding: "A" → "QQ"

Decoding without padding (JavaScript):

function decodeNoPadding(str) {
  // Calculate required padding
  const remainder = str.length % 4;
  if (remainder) {
    const padding = 4 - remainder;
    str += '='.repeat(padding);
  }
  return atob(str);
}

When to use: JWTs, URL parameters, anywhere saving a few bytes matters.

Base32 and Base16 (Hex)

Base32: Uses 32 characters (A-Z and 2-7)

• Advantages: Case-insensitive, avoids ambiguous characters
• Disadvantages: ~20% larger than Base64
• Uses: TOTP secrets, Crockford’s Base32 for human-readable codes

Base16 (Hex): Uses 16 characters (0-9, A-F)

• Advantages: Simple, widely understood, easy debugging
• Disadvantages: 100% size increase (double original size)
• Uses: Color codes, checksums, cryptographic hashes

Size comparison for 100 bytes:

• Original: 100 bytes
• Base16: 200 bytes (100% increase)
• Base32: 160 bytes (60% increase)
• Base64: 133 bytes (33% increase)

Tools: Generate and verify checksums with our Checksum Calculator and create hashes with our Hash Generator.

Security Considerations

⚠️ Critical misconception: Base64 is NOT encryption!

Base64 is NOT Encryption

What Base64 does: Converts data from one format to another (encoding)

What encryption does: Makes data unreadable without a secret key

The difference:

Base64 encoding:
"password123" → "cGFzc3dvcmQxMjM="
Anyone can decode this instantly!

Encryption (AES-256):
"password123" + secret_key → "U2FsdGVkX1+F8vCJ..."
Requires the secret key to decrypt

Real-world mistake:

// ❌ WRONG - This provides ZERO security
const password = "admin123";
const "secured" = btoa(password);  // "YWRtaW4xMjM="
// Anyone can decode: atob("YWRtaW4xMjM=") → "admin123"

// ✅ CORRECT - Use proper encryption
const encrypted = CryptoJS.AES.encrypt(password, secretKey);

Remember: Base64 obscures data (makes it look scrambled), but does NOT secure it.

When to Use Base64 vs. Encryption

Use our Encryption tool when you need actual security, not just encoding.

Common Security Mistakes

Mistake 1: Using Base64 for password storage

// ❌ TERRIBLE - Never do this
const hashedPassword = btoa(userPassword);
database.save({ password: hashedPassword });

// ✅ CORRECT - Use proper password hashing
const bcrypt = require('bcrypt');
const hashedPassword = await bcrypt.hash(userPassword, 10);
database.save({ password: hashedPassword });

Mistake 2: Assuming Basic Auth is secure without HTTPS

// ❌ INSECURE - credentials visible on network
http://example.com
Authorization: Basic YWRtaW46cGFzc3dvcmQ=

// ✅ SECURE - HTTPS encrypts the entire connection
https://example.com
Authorization: Basic YWRtaW46cGFzc3dvcmQ=

Mistake 3: Storing API keys in client-side code

// ❌ EXPOSED - anyone can view source and decode
const apiKey = "c2VjcmV0X2tleV8xMjM="; // Just Base64!
fetch(`https://api.example.com?key=${atob(apiKey)}`);

// ✅ CORRECT - API keys should never be in client code
// Use environment variables and backend proxy
const response = await fetch('/api/proxy-endpoint');

Mistake 4: Trusting user-provided Base64 data

// ❌ DANGEROUS - could contain malicious code
const userInput = req.body.data;
const decoded = Buffer.from(userInput, 'base64');
eval(decoded.toString());  // NEVER DO THIS!

// ✅ CORRECT - validate and sanitize
const userInput = req.body.data;
const decoded = Buffer.from(userInput, 'base64');
const validated = validateImage(decoded);  // Check file type, size, etc.

Base64 in JWT Tokens

JWT tokens use Base64URL encoding for header and payload, but the signature provides security.

JWT structure:

<base64-header>.<base64-payload>.<signature>

Security facts:

• Header and payload: Anyone can decode and read these (they’re just Base64)
• Signature: Cryptographically verifies the token hasn’t been tampered with
• Never put secrets in JWT payload: It’s public information!

Example - What NOT to do:

// ❌ BAD - sensitive data visible to anyone
const token = jwt.sign({
  userId: 123,
  password: "secretpass",      // Anyone can decode this!
  creditCard: "4532-1234-5678", // Terrible idea!
}, secretKey);

Correct approach:

// ✅ GOOD - only non-sensitive data
const token = jwt.sign({
  userId: 123,
  role: "admin",
  exp: 1642089600
}, secretKey);
// Sensitive data stays on server, looked up by userId

Tools: Analyze JWT tokens safely with our JWT Decoder to inspect claims and verify structure.

Performance and File Size

Base64 encoding has performance implications you need to understand.

The 33% Size Increase

Mathematical reason: Base64 represents 3 bytes (24 bits) with 4 characters (32 bits).

Original:  3 bytes = 24 bits
Encoded:   4 bytes = 32 bits
Overhead:  33.33% increase

Real-world examples:

Impact on web performance:

<!-- Original image: 50 KB -->
<img src="icon.png">  <!-- Downloads 50 KB -->

<!-- Base64 embedded: 66.5 KB -->
<img src="data:image/png;base64,...">  <!-- Page HTML is 66.5 KB larger -->

When the 33% overhead is worth it:

• Small files under 5 KB (saved HTTP request is worth the overhead)
• One-time use files that won’t be cached
• Critical resources needed immediately on page load

When it’s NOT worth it:

• Large files over 100 KB (overhead too expensive)
• Reused assets that benefit from caching
• Images used multiple times (download once, use many times)

Compression Before Encoding

Pro tip: Compress data before Base64 encoding to reduce final size.

Example with gzip:

const pako = require('pako');

// Original JSON data
const data = JSON.stringify(largeObject);
console.log('Original:', data.length);  // 50,000 bytes

// Compress, then encode
const compressed = pako.gzip(data);
const encoded = Buffer.from(compressed).toString('base64');
console.log('Compressed + Base64:', encoded.length);  // ~8,000 bytes

// Savings: 84% smaller!

Python example:

import gzip
import base64

# Original data
data = b"Large repetitive data..." * 1000

# Compress then encode
compressed = gzip.compress(data)
encoded = base64.b64encode(compressed)

print(f"Original: {len(data)} bytes")
print(f"Compressed + Base64: {len(encoded)} bytes")
print(f"Savings: {100 - (len(encoded)/len(data)*100):.1f}%")

When to compress:

• Text data (JSON, XML, logs)
• Repetitive binary data
• Large data (over 1 KB)

When NOT to compress:

• Already compressed data (images, videos)
• Small data (overhead not worth it)
• Real-time streaming (latency concerns)

Performance Benchmarks

Encoding/decoding speed test (10,000 iterations):

Key takeaway: Base64 operations are fast for small data but can become a bottleneck for large files.

Optimization tips:

1. Use native functions (btoa, atob, Buffer) instead of libraries
2. Encode once, cache results instead of re-encoding repeatedly
3. Stream large files instead of loading entirely into memory
4. Consider alternatives for large binary transfers (multipart uploads, signed URLs)

When to Use Alternatives

Instead of Base64, consider:

Rule of thumb: Use Base64 for convenience with small data. Use binary transfer for efficiency with large data.

Practical Examples and Code

Let’s walk through real-world scenarios you’ll encounter.

Example 1: Embed Image as Data URL

Scenario: You want to embed a logo in your HTML to reduce HTTP requests.

Step 1: Convert image to Base64 (Node.js)

const fs = require('fs');

const imageBuffer = fs.readFileSync('logo.png');
const base64Image = imageBuffer.toString('base64');
const dataUrl = `data:image/png;base64,${base64Image}`;

console.log(dataUrl);
// Output: data:image/png;base64,iVBORw0KGgo...

Step 2: Use in HTML

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..." alt="Logo">

Step 3: Or use in CSS

.logo {
  background-image: url(data:image/png;base64,iVBORw0KGgo...);
  width: 100px;
  height: 50px;
}

Quick method: Use our Image to Base64 tool to upload and convert images instantly.

Example 2: Decode JWT Token

Scenario: You received a JWT and need to inspect its contents.

JWT example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMzQ1LCJ1c2VybmFtZSI6ImpvaG5kb2UiLCJyb2xlIjoiYWRtaW4iLCJleHAiOjE3MDY3MDcyMDB9.6rqZ8Qz-mYKJLc9P0C4uGvJ4nQoKr7xK8vN2hV8mLxo

Decode manually (JavaScript):

const jwt = "eyJhbGci...";
const parts = jwt.split('.');

// Decode header
const header = JSON.parse(atob(parts[0]));
console.log('Header:', header);
// { alg: "HS256", typ: "JWT" }

// Decode payload
const payload = JSON.parse(atob(parts[1]));
console.log('Payload:', payload);
// { userId: 12345, username: "johndoe", role: "admin", exp: 1706707200 }

// Note: Signature (parts[2]) requires verification with secret key

Decode manually (Python):

import base64
import json

jwt = "eyJhbGci..."
parts = jwt.split('.')

# Decode header
header = json.loads(base64.b64decode(parts[0] + '=='))
print('Header:', header)

# Decode payload
payload = json.loads(base64.b64decode(parts[1] + '=='))
print('Payload:', payload)

Quick method: Use our JWT Decoder tool for instant decoding and validation.

Example 3: Basic Auth Header

Scenario: Call an API that requires Basic Authentication.

Creating the header (JavaScript):

const username = "api_user";
const password = "api_key_12345";

const credentials = `${username}:${password}`;
const encoded = btoa(credentials);
const authHeader = `Basic ${encoded}`;

// Use in fetch request
fetch('https://api.example.com/data', {
  headers: {
    'Authorization': authHeader
  }
})
.then(response => response.json())
.then(data => console.log(data));

Creating the header (Python):

import base64
import requests

username = "api_user"
password = "api_key_12345"

credentials = f"{username}:{password}"
encoded = base64.b64encode(credentials.encode()).decode()
auth_header = f"Basic {encoded}"

response = requests.get(
    'https://api.example.com/data',
    headers={'Authorization': auth_header}
)
print(response.json())

Creating the header (cURL):

# cURL has built-in Basic Auth support
curl -u api_user:api_key_12345 https://api.example.com/data

# Or manually with Base64
AUTH=$(echo -n "api_user:api_key_12345" | base64)
curl -H "Authorization: Basic $AUTH" https://api.example.com/data

⚠️ Security reminder: Always use HTTPS with Basic Auth! The credentials are only Base64-encoded, not encrypted.

Example 4: Send File via JSON API

Scenario: Upload a file through a JSON API that doesn’t support multipart form data.

Client-side (JavaScript):

async function uploadFile(file) {
  // Read file as data URL
  const reader = new FileReader();

  return new Promise((resolve, reject) => {
    reader.onload = async (e) => {
      const dataUrl = e.target.result;

      // Extract Base64 part (remove "data:image/png;base64," prefix)
      const base64 = dataUrl.split(',')[1];

      // Send to API
      const response = await fetch('/api/upload', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          filename: file.name,
          content: base64,
          mimetype: file.type
        })
      });

      resolve(await response.json());
    };

    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
}

// Usage
document.getElementById('fileInput').addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const result = await uploadFile(file);
  console.log('Upload result:', result);
});

Server-side (Node.js/Express):

app.post('/api/upload', (req, res) => {
  const { filename, content, mimetype } = req.body;

  // Decode Base64 to buffer
  const buffer = Buffer.from(content, 'base64');

  // Save to disk
  const fs = require('fs');
  const filepath = `./uploads/${filename}`;
  fs.writeFileSync(filepath, buffer);

  res.json({
    success: true,
    filepath: filepath,
    size: buffer.length
  });
});

Server-side (Python/Flask):

from flask import Flask, request, jsonify
import base64

app = Flask(__name__)

@app.route('/api/upload', methods=['POST'])
def upload():
    data = request.json
    filename = data['filename']
    content = data['content']

    # Decode Base64
    file_bytes = base64.b64decode(content)

    # Save to disk
    filepath = f"./uploads/{filename}"
    with open(filepath, 'wb') as f:
        f.write(file_bytes)

    return jsonify({
        'success': True,
        'filepath': filepath,
        'size': len(file_bytes)
    })

Important note: For files over 1 MB, consider using multipart form data instead of JSON+Base64 for better performance.

Example 5: Store Binary Data in JSON

Scenario: You need to cache API responses that include binary data in localStorage or a JSON file.

Storing data:

const imageResponse = await fetch('https://api.example.com/image');
const imageBlob = await imageResponse.blob();

// Convert blob to Base64
const reader = new FileReader();
reader.onloadend = () => {
  const base64 = reader.result.split(',')[1];

  // Store in localStorage
  const cacheData = {
    url: 'https://api.example.com/image',
    timestamp: Date.now(),
    content: base64,
    contentType: imageBlob.type
  };

  localStorage.setItem('cachedImage', JSON.stringify(cacheData));
};
reader.readAsDataURL(imageBlob);

Retrieving data:

const cached = JSON.parse(localStorage.getItem('cachedImage'));

if (cached) {
  // Recreate image from Base64
  const dataUrl = `data:${cached.contentType};base64,${cached.content}`;

  // Use in img tag
  document.getElementById('myImage').src = dataUrl;

  // Or convert to Blob for processing
  const blob = await fetch(dataUrl).then(r => r.blob());
}

Storage limits:

• localStorage: 5-10 MB limit
• SessionStorage: 5-10 MB limit
• IndexedDB: Much larger (50+ MB)

Recommendation: For caching larger files, use IndexedDB with Blob storage instead of Base64.

Common Errors and How to Fix Them

Let’s troubleshoot the most frequent Base64 issues.

Error 1: Invalid Base64 String

Symptoms:

Error: Invalid character in base64 string
DOMException: Failed to execute 'atob'

Causes:

1. String contains non-Base64 characters
2. Incorrect padding
3. Whitespace or newlines in string

Diagnosis:

function isValidBase64(str) {
  // Base64 should only contain these characters
  const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
  return base64Regex.test(str);
}

const input = "SGVsbG8gV29ybGQh";
console.log(isValidBase64(input));  // true

const badInput = "SGVs bG8gV29ybGQh";  // Contains space
console.log(isValidBase64(badInput));  // false

Solutions:

Remove whitespace:

const encoded = "SGVs bG8g\nV29y bGQh";  // Has spaces and newlines
const cleaned = encoded.replace(/\s/g, '');  // Remove all whitespace
const decoded = atob(cleaned);  // Now works!

Fix padding:

function fixPadding(base64) {
  // Add missing padding
  while (base64.length % 4 !== 0) {
    base64 += '=';
  }
  return base64;
}

const noPadding = "SGVsbG8";  // Missing padding
const fixed = fixPadding(noPadding);  // "SGVsbG8="
const decoded = atob(fixed);  // Works!

Validate before decoding:

function safeBase64Decode(str) {
  try {
    // Remove whitespace
    str = str.replace(/\s/g, '');

    // Validate characters
    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(str)) {
      throw new Error('Invalid Base64 characters');
    }

    // Fix padding
    while (str.length % 4 !== 0) {
      str += '=';
    }

    return atob(str);
  } catch (error) {
    console.error('Base64 decode error:', error);
    return null;
  }
}

Test your Base64 strings with our Encoder tool to quickly identify issues.

Error 2: Unicode Encoding Problems

Symptoms:

Error: String contains an invalid character
Error: The string to be encoded contains characters outside of the Latin1 range

Problem: btoa() and atob() only handle ASCII characters (0-255). Unicode characters (emojis, non-Latin scripts) cause errors.

Bad approach:

const text = "Hello 世界! 🌍";
const encoded = btoa(text);  // ❌ Error!

Solution 1: TextEncoder API (modern browsers)

function encodeUnicode(str) {
  const bytes = new TextEncoder().encode(str);
  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
  return btoa(binString);
}

function decodeUnicode(base64) {
  const binString = atob(base64);
  const bytes = Uint8Array.from(binString, c => c.codePointAt(0));
  return new TextDecoder().decode(bytes);
}

const text = "Hello 世界! 🌍";
const encoded = encodeUnicode(text);
const decoded = decodeUnicode(encoded);
console.log(decoded);  // "Hello 世界! 🌍"

Solution 2: encodeURIComponent (works everywhere)

function encodeUnicode(str) {
  return btoa(unescape(encodeURIComponent(str)));
}

function decodeUnicode(base64) {
  return decodeURIComponent(escape(atob(base64)));
}

const text = "Hello 世界! 🌍";
const encoded = encodeUnicode(text);  // Works!
const decoded = decodeUnicode(encoded);  // "Hello 世界! 🌍"

Solution 3: Use Buffer in Node.js

const text = "Hello 世界! 🌍";
const encoded = Buffer.from(text, 'utf-8').toString('base64');
const decoded = Buffer.from(encoded, 'base64').toString('utf-8');
console.log(decoded);  // "Hello 世界! 🌍"

Error 3: Data URL Not Working

Symptoms:

• Image doesn’t display
• “Failed to load resource” error
• Broken image icon

Common causes:

Missing data URL prefix:

// ❌ WRONG - just Base64 string
<img src="iVBORw0KGgoAAAANSUhEUg...">

// ✅ CORRECT - full data URL
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...">

Wrong MIME type:

// ❌ WRONG - incorrect type
const dataUrl = `data:image/jpg;base64,${base64}`;  // Should be "jpeg"

// ✅ CORRECT - proper MIME type
const dataUrl = `data:image/jpeg;base64,${base64}`;

Common MIME types:

• PNG: image/png
• JPEG: image/jpeg
• GIF: image/gif
• SVG: image/svg+xml
• PDF: application/pdf
• Plain text: text/plain

Size limits:

• Browsers have limits on data URL length (typically 2-4 MB)
• For larger files, use Blob URLs instead:

// Convert large Base64 to Blob URL
function base64ToBlobUrl(base64, mimeType) {
  const byteString = atob(base64);
  const bytes = new Uint8Array(byteString.length);
  for (let i = 0; i < byteString.length; i++) {
    bytes[i] = byteString.charCodeAt(i);
  }
  const blob = new Blob([bytes], { type: mimeType });
  return URL.createObjectURL(blob);
}

const blobUrl = base64ToBlobUrl(largeBase64, 'image/jpeg');
document.getElementById('myImage').src = blobUrl;

// Remember to revoke when done
URL.revokeObjectURL(blobUrl);

Error 4: Incorrect Decoding Output

Symptoms:

• Decoded text looks garbled
• File is corrupted after decode
• Wrong characters appear

Cause 1: Wrong encoding assumption

// Original text in UTF-16
const text = "Test";
const wrongEncoded = btoa(text);  // Assumes Latin1

// Better: specify encoding
const buffer = Buffer.from(text, 'utf16le');
const correctEncoded = buffer.toString('base64');

Cause 2: Double encoding

// Accidentally encoded twice
const text = "Hello";
const once = btoa(text);         // "SGVsbG8="
const twice = btoa(once);         // "U0dWc2JHOD0="

// Decoding once gives wrong result
atob(twice);  // "SGVsbG8=" (still encoded!)

// Need to decode twice
atob(atob(twice));  // "Hello" (correct!)

Cause 3: Line breaks in Base64

// Some systems add line breaks every 76 characters
const withLineBreaks = `
SGVsbG8gV29ybGQhIFRoaXMgaXMgYSB0ZXN0IG9mIGEgbG9uZyBCYXNlNjQgZW5jb2RlZCBzdHJpbmcg
dGhhdCBpcyBicm9rZW4gaW50byBtdWx0aXBsZSBsaW5lcy4gVGhpcyBpcyBjb21tb24gaW4gZW1haWwg
YW5kIFBFTSBmb3JtYXRzLg==
`;

// Remove line breaks before decoding
const clean = withLineBreaks.replace(/\s/g, '');
const decoded = atob(clean);  // Now works!

Frequently Asked Questions

Is Base64 encryption?

No. Base64 is encoding, not encryption.

Encoding changes data format (binary → text). Anyone can reverse it.

Encryption secures data with a key. Only those with the key can decrypt it.

Think of it this way:

• Base64 is like translating English to Spanish—anyone with a dictionary can translate back
• Encryption is like using a secret code—only those with the codebook can understand

Never use Base64 for security. Use proper encryption like AES, RSA, or dedicated authentication systems.

Why does Base64 increase file size by 33%?

Mathematical reason: Base64 represents 3 bytes with 4 characters.

Input:  3 bytes × 8 bits = 24 bits
Output: 4 chars × 6 bits = 24 bits (stored in 32-bit space)
Waste:  4 chars × 8 bits = 32 bits total = 8 bits wasted

Efficiency: 24/32 = 75% (meaning 25% overhead, but accounting for padding brings it to ~33%)

This overhead is the trade-off for making binary data text-safe.

Can I decode Base64 without tools?

Technically yes, but it’s tedious. You’d need to:

1. Look up each character in the Base64 table to get its 6-bit value
2. Concatenate all 6-bit values into a binary string
3. Split into 8-bit groups
4. Convert each 8-bit group to a character

Practical answer: Use built-in functions (atob(), base64 command) or our Encoder tool. Life’s too short for manual Base64 decoding.

Is URL-safe Base64 compatible with standard Base64?

Not directly. You need to convert between them.

Differences:

• Standard: uses +, /, and =
• URL-safe: uses -, _, and no padding

Convert URL-safe to standard:

function urlSafeToStandard(base64url) {
  let base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
  while (base64.length % 4) {
    base64 += '=';
  }
  return base64;
}

Most Base64 libraries have built-in conversion functions.

Should I Base64 encode images for websites?

Yes, if:

• Image is under 5 KB
• Image is used once on a page
• Image is critical for initial render
• You want to reduce HTTP requests

No, if:

• Image is over 10 KB
• Image is used multiple times
• Image benefits from caching
• Page load performance is critical

Best practice: Inline critical above-the-fold images under 5 KB. Load everything else as separate files.

What’s the maximum size for Base64 in URLs?

Practical limits:

• Browsers: 2,000-8,000 characters in URL (varies)
• Servers: Many limit to 2,048 bytes
• CDNs/Proxies: Often limit to 2,000-4,000 characters

Recommendations:

• Keep Base64 URL parameters under 1,000 characters
• For larger data, use POST requests with JSON body
• Use short-lived signed URLs instead for large transfers

How do I validate Base64 strings?

JavaScript validation:

function isValidBase64(str) {
  // Check format
  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(str)) {
    return false;
  }

  // Check length (must be multiple of 4)
  if (str.length % 4 !== 0) {
    return false;
  }

  // Try decoding
  try {
    atob(str);
    return true;
  } catch (e) {
    return false;
  }
}

Python validation:

import base64
import re

def is_valid_base64(s):
    # Check format
    if not re.match(r'^[A-Za-z0-9+/]*={0,2}$', s):
        return False

    # Check length
    if len(s) % 4 != 0:
        return False

    # Try decoding
    try:
        base64.b64decode(s, validate=True)
        return True
    except Exception:
        return False

Use our Encoder tool for quick validation and error detection.

Can Base64 contain spaces or newlines?

Technically: No. Standard Base64 should not contain whitespace.

In practice: Many encoders add line breaks every 64-76 characters for readability (MIME standard).

Example:

SGVsbG8gV29ybGQhIFRoaXMgaXMgYSB0ZXN0IG9mIGEgbG9uZyBCYXNlNjQgZW5jb2RlZCBzdHJp
bmcgdGhhdCBpcyBicm9rZW4gaW50byBtdWx0aXBsZSBsaW5lcy4=

Decoding: Most decoders automatically ignore whitespace, but it’s safer to strip it first:

const cleaned = base64String.replace(/\s/g, '');
const decoded = atob(cleaned);

What’s the difference between Base64 and Base64URL?

Why URL-safe exists: Characters +, /, and = have special meanings in URLs and need escaping. Base64URL avoids this.

How secure are JWT tokens if they’re just Base64?

JWT security comes from the signature, not the encoding.

What’s visible (Base64-encoded):

• Header (algorithm, token type)
• Payload (claims, user info)

What’s secure (cryptographically signed):

• Signature (proves token wasn’t tampered with)

Best practices:

• Don’t put secrets in JWT payload (anyone can decode it)
• Always verify the signature before trusting token
• Use HTTPS to prevent token interception
• Set short expiration times to limit damage if stolen

Tools: Inspect JWT tokens securely with our JWT Decoder.

Conclusion: When and How to Use Base64

After 4,000+ words, here’s what you need to remember:

Base64 is a tool for format conversion, not security. It converts binary data to text so it can pass through text-only systems. That’s it.

Use Base64 when:

• Embedding small images in HTML/CSS (under 5 KB)
• Sending files through JSON APIs
• Storing binary data in text fields
• Working with email attachments (MIME)
• Handling data in JWT tokens
• Creating Basic Authentication headers

Don’t use Base64 when:

• You need encryption or security (use AES, RSA, proper hashing)
• Transferring large files (use binary uploads, signed URLs)
• Performance is critical (33% size overhead)
• Standard binary transfer works fine

Key facts to remember:

1. Base64 increases size by ~33%
2. It’s reversible (not secure)
3. URLs need URL-safe Base64
4. Always use HTTPS with sensitive Base64 data
5. Compression before encoding saves space

Common mistakes to avoid:

• Thinking Base64 is encryption
• Encoding huge files unnecessarily
• Forgetting to handle Unicode properly
• Not validating decoded data
• Using it when binary transfer works better

Your Base64 Toolkit

Essential tools for working with Base64:

Encoding & Decoding:

• Encoder/Decoder - Convert text and data to/from Base64
• Image to Base64 - Convert images to data URLs
• JWT Decoder - Decode and inspect JWT tokens

Security & Validation:

• Encryption Tool - When you need actual security
• Hash Generator - Create secure hashes for verification
• Checksum Calculator - Verify file integrity

Text Processing:

• String Case Converter - Convert naming conventions
• Random String Generator - Generate secure tokens
• UUID Generator - Create unique identifiers

Development Tools:

• Formatter - Format JSON, XML, and code
• Diff Tool - Compare encoded/decoded outputs
• HTTP Headers Checker - Inspect authentication headers

View all tools: Developer Tools

Next Steps

Now that you understand Base64:

1. Bookmark our tools for quick encoding/decoding tasks
2. Review your projects for Base64 security mistakes (encoding ≠ encryption!)
3. Optimize file transfers by using binary when appropriate
4. Implement proper Unicode handling in your code
5. Share this guide with your team to prevent common mistakes

Additional Resources

Official specifications:

• RFC 4648 - Base64 official specification
• MDN Web Docs: btoa() - Browser API reference
• MDN Web Docs: atob() - Decoding reference

Related topics:

• JSON vs XML vs YAML - Choosing data formats
• JWT Tokens - Understanding web authentication
• Encryption vs Encoding vs Hashing - Security fundamentals

---

Found this helpful? Share it with your team and bookmark our developer tools for your next project.

Questions or feedback? Contact us or follow us on Twitter for more development tips.

---

Last Updated: January 30, 2025
Reading Time: 14 minutes
Author: Orbit2x Team

Share This Guide

• Twitter
• LinkedIn
• Facebook