Why Base64-encode JSON?
JSON is already a text format, so encoding it as Base64 might sound redundant. It's not — Base64 solves specific transport problems that plain JSON does not. Anywhere the surrounding channel has restrictions on characters, size, or byte range, Base64 turns your JSON into a compact ASCII-only string that fits.
The three most common places you'll encode JSON to Base64: JWT tokens (each JWT segment is Base64URL(JSON)), HTTP headers like Authorization or X-Custom-Metadata which must be ASCII per RFC 7230, and URL query parameters or cookies where JSON's braces, quotes, and colons would need aggressive URL-encoding anyway. Base64 sidesteps all of that with a single string of safe characters.
UTF-8 safety — the btoa() trap
Naive JavaScript uses btoa() to Base64-encode strings — but btoa() throws InvalidCharacterError on any code point above U+00FF. If your JSON contains emoji, CJK text, Arabic, or any Unicode above Latin-1, btoa(JSON.stringify(obj)) crashes. The fix is to encode the JSON as UTF-8 bytes first, then Base64 those bytes:
Correct JavaScript (browser)
const obj = { name: '田中', emoji: '🚀' };
const json = JSON.stringify(obj);
const utf8 = new TextEncoder().encode(json);
const base64 = btoa(String.fromCharCode(...utf8));
// Or more robust for very large objects:
const base64Safe = btoa([...utf8].map(b => String.fromCharCode(b)).join(''));Node.js
const obj = { name: '田中', emoji: '🚀' };
const base64 = Buffer.from(JSON.stringify(obj), 'utf8').toString('base64');Python
import base64, json
obj = { 'name': '田中', 'emoji': '🚀' }
base64_str = base64.b64encode(json.dumps(obj).encode('utf-8')).decode('ascii')
print(base64_str)JWT payloads — a worked example
A JWT (JSON Web Token, RFC 7519) has three Base64URL segments: header.payload.signature. Both header and payload are JSON objects. To construct a JWT payload manually, minify the JSON, encode as UTF-8, then Base64URL-encode:
JWT payload construction
// Payload JSON:
{"sub":"user_123","iat":1717000000,"exp":1717086400,"role":"admin"}
// After Base64URL encoding (this is the middle segment of a JWT):
eyJzdWIiOiJ1c2VyXzEyMyIsImlhdCI6MTcxNzAwMDAwMCwiZXhwIjoxNzE3MDg2NDAwLCJyb2xlIjoiYWRtaW4ifQ
// Full JWT:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzEyMyIsImlhdCI6MTcxNzAwMDAwMCwiZXhwIjoxNzE3MDg2NDAwLCJyb2xlIjoiYWRtaW4ifQ.SIGNATUREHTTP Basic Auth — the other classic use
HTTP Basic Auth (RFC 7617) sends credentials as Authorization: Basic BASE64(username:password). When the username or password is structured data (rare but happens with API keys that embed JSON metadata), you'd Base64-encode the JSON string and use it as the credential value. Note this is different from Bearer tokens — Basic Auth uses the user:pass format inside the Base64, so JSON goes on one side of the colon.
Config secrets and Kubernetes
Kubernetes Secrets store all values as Base64 in their YAML representation. To create a Secret with a JSON config file inline, encode the JSON:
Kubernetes Secret example
# secret.yaml
apiVersion: v1
kind: Secret
metadata:
name: api-config
type: Opaque
data:
config.json: eyJhcGlfa2V5IjoiYWJjMTIzIiwiZW52IjoicHJvZCJ9Related Base64 & Encoding Tools
- Base64 Encoder (Parent Tool) — the underlying encoder used by every variant on this page
- Base64 Encode Online — general-purpose text encoder with copy-to-clipboard
- Text to Base64 — convert plain text or UTF-8 to Base64
- Base64 Encode in JavaScript — btoa(), TextEncoder, and Buffer.from() patterns
- Base64 Encode in Python — base64.b64encode() reference and examples
- Base64 Decoder — reverse the encoding — Base64 back to text or file
- Base64 to Image Converter — decode a data URI back into a viewable image file