Base64 Encoding in Practice: 7 Real-World Uses Every Developer Should Know

Base64 is everywhere in web development, but most tutorials only explain how it works. This article focuses on the 7 real-world scenarios where you’ll actually use Base64 encoding in your daily development work, with code examples you can copy directly.

Try our Base64 Encoder/Decoder tool →

1. Embedding Images in HTML/CSS (Data URIs)

Data URIs let you embed small images directly in your HTML or CSS, eliminating an HTTP request. This is particularly useful for icons, logos, and tiny UI elements.

<!-- Embed a small icon directly in HTML -->
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEU..." alt="icon" />

/* Embed in CSS */
.icon {
  background-image: url('data:image/svg+xml;base64,PHN2Zy...');
}

When to use: Images under 10KB (icons, small logos, UI elements).

When NOT to use: Images over 10KB — the 33% size increase outweighs the saved HTTP request.

// Node.js: Convert image file to Base64 data URI
const fs = require('fs');
const imageBuffer = fs.readFileSync('icon.png');
const base64 = imageBuffer.toString('base64');
const dataUri = `data:image/png;base64,${base64}`;
console.log(dataUri);

Convert images to Base64 with our encoder →

2. JWT Token Structure

JSON Web Tokens (JWT) use Base64URL encoding (a URL-safe variant) for their three parts: header, payload, and signature. Understanding this is essential for debugging authentication issues.

// A JWT token:
// eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiam9obiJ9.signature
//  ^^^^^ header ^^^^^   ^^^^^ payload ^^^^^

// Decoding the header (Base64URL → JSON):
atob('eyJhbGciOiJIUzI1NiJ9');
// → '{"alg":"HS256"}'

// Decoding the payload:
atob('eyJ1c2VyIjoiam9obiJ9');
// → '{"user":"john"}'

Key insight: JWT tokens are not encrypted. Anyone can decode the header and payload with a simple Base64 decode. The signature verifies integrity, not secrecy.

Decode JWT tokens with our JWT Decoder →

3. Kubernetes Secrets

Kubernetes stores secret values as Base64-encoded strings in YAML manifests. This is one of the most common Base64 use cases in DevOps.

# Creating a Kubernetes Secret
apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
type: Opaque
data:
  DB_PASSWORD: c3VwZXItc2VjcmV0  # echo -n 'super-secret' | base64
  DB_USER: YWRtaW4=              # echo -n 'admin' | base64

# Encode a value for Kubernetes secrets
echo -n 'my-password' | base64
# → bXktcGFzc3dvcmQ=

# Decode a Kubernetes secret value
echo -n 'bXktcGFzc3dvcmQ=' | base64 --decode
# → my-password

# IMPORTANT: Always use -n with echo to avoid trailing newline!

Security warning: Base64 in Kubernetes secrets is for encoding, not encryption. Use solutions like Sealed Secrets, External Secrets, or Vault for real security.

4. API Request/Response Payloads

When APIs need to transmit binary data (images, files, certificates) within JSON payloads, Base64 encoding is the standard approach since JSON only supports text.

// Uploading an image via API
const fileInput = document.getElementById('avatar');
const file = fileInput.files[0];

const reader = new FileReader();
reader.onload = async () => {
  const base64 = reader.result.split(',')[1]; // Remove data URI prefix

  await fetch('/api/upload-avatar', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      filename: file.name,
      data: base64,        // Base64-encoded file content
      contentType: file.type,
    }),
  });
};
reader.readAsDataURL(file);

5. HTTP Basic Authentication

The HTTP Basic Authentication scheme transmits credentials as a Base64-encoded string in the Authorization header. This is still used in many APIs.

// Constructing Basic Auth header
const username = 'admin';
const password = 'secret123';
const credentials = btoa(`${username}:${password}`);
// → "YWRtaW46c2VjcmV0MTIz"

// Using in fetch
fetch('https://api.example.com/data', {
  headers: {
    'Authorization': `Basic ${credentials}`,
  },
});

// curl equivalent
// curl -u admin:secret123 https://api.example.com/data
// (curl Base64-encodes automatically with -u)

Always use HTTPS with Basic Auth. Over plain HTTP, Base64 credentials can be trivially decoded by anyone intercepting the traffic.

6. Email Attachments (MIME)

Email protocols (SMTP) were designed for ASCII text only. Binary attachments — images, PDFs, documents — are Base64-encoded before being included in email messages via MIME.

// Node.js: Sending email with attachment (nodemailer)
const nodemailer = require('nodemailer');
const fs = require('fs');

const pdfBuffer = fs.readFileSync('report.pdf');

await transporter.sendMail({
  from: 'sender@example.com',
  to: 'recipient@example.com',
  subject: 'Monthly Report',
  attachments: [
    {
      filename: 'report.pdf',
      content: pdfBuffer,
      // nodemailer handles Base64 encoding internally
      encoding: 'base64',
    },
  ],
});

Behind the scenes, the MIME message looks like:

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

JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMg
MCBSPj4Kc3RyZWFtCkJUCi9GMS...

7. Storing Binary Data in Text-Only Systems

Some systems — environment variables, JSON config files, CSV exports — only support text. Base64 lets you safely embed binary data in these text-only contexts.

# .env file: Store SSL certificate as Base64
SSL_CERT=LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...
SSL_KEY=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t...

# In your application:
# const cert = Buffer.from(process.env.SSL_CERT, 'base64');

// Storing binary config in JSON
{
  "favicon": "iVBORw0KGgoAAAANSUhEUgAAA...",
  "sslCert": "LS0tLS1CRUdJTiBDRVJUSUZJ..."
}

This pattern is commonly used in cloud platforms (Heroku, Railway, Fly.io) where environment variables are the primary configuration mechanism.

Base64 vs Base64URL

Standard Base64 uses + and / which are not safe in URLs. Base64URL replaces them with - and _:

Quick Reference: Base64 Commands

# Encode a string
echo -n 'Hello World' | base64
# → SGVsbG8gV29ybGQ=

# Decode a string
echo -n 'SGVsbG8gV29ybGQ=' | base64 --decode
# → Hello World

# Encode a file
base64 < input.bin > output.txt

# Decode a file
base64 --decode < encoded.txt > output.bin

# JavaScript (browser)
btoa('Hello World')        // encode
atob('SGVsbG8gV29ybGQ=')  // decode

# Python
import base64
base64.b64encode(b'Hello World')
base64.b64decode(b'SGVsbG8gV29ybGQ=')

Encode and decode Base64 instantly with our tool →