Base64 Encoding and Decoding API Guide

Base64 encoding is essential for handling binary data in text-based protocols. This guide covers how to encode and decode Base64 using a simple REST API, including URL-safe variants and Unicode handling.

What is Base64?

Base64 is a binary-to-text encoding scheme that represents binary data using 64 ASCII characters. It converts every 3 bytes of input into 4 characters of output, making binary data safe for text-based systems.

The standard Base64 alphabet uses: A-Z, a-z, 0-9, +, /, and = for padding.

When to Use Base64

• Email attachments: MIME encoding for binary attachments
• Data URIs: Embedding images in HTML/CSS
• API payloads: Sending binary data in JSON
• Basic authentication: HTTP Basic Auth headers
• Storing binary in text fields: Database text columns

API Usage

Encode Text to Base64

GET https://api.tinyfn.io/v1/encode/base64/encode?text=Hello%20World
Headers: X-API-Key: your-api-key

{
  "original": "Hello World",
  "encoded": "SGVsbG8gV29ybGQ=",
  "length": 16
}

Decode Base64 to Text

GET https://api.tinyfn.io/v1/encode/base64/decode?encoded=SGVsbG8gV29ybGQ=
Headers: X-API-Key: your-api-key

{
  "encoded": "SGVsbG8gV29ybGQ=",
  "decoded": "Hello World",
  "is_valid": true
}

URL-Safe Base64

Standard Base64 uses + and / which have special meaning in URLs. URL-safe Base64 replaces these with - and _.

GET /v1/encode/base64/encode?text=Hello&url_safe=true

Code Examples

JavaScript - Encode User Data

async function encodeUserData(data) {
  const text = JSON.stringify(data);
  const response = await fetch(
    `https://api.tinyfn.io/v1/encode/base64/encode?text=${encodeURIComponent(text)}`,
    { headers: { 'X-API-Key': API_KEY } }
  );
  const { encoded } = await response.json();
  return encoded;
}

// Encode a user object
const encoded = await encodeUserData({ id: 123, name: 'Alice' });
// Result: eyJpZCI6MTIzLCJuYW1lIjoiQWxpY2UifQ==

Python - Decode JWT Payload

import requests
import json

def decode_jwt_payload(jwt_token: str) -> dict:
    """Decode the payload portion of a JWT."""
    # JWT format: header.payload.signature
    payload_b64 = jwt_token.split('.')[1]

    response = requests.get(
        'https://api.tinyfn.io/v1/encode/base64/decode',
        params={'encoded': payload_b64, 'url_safe': True},
        headers={'X-API-Key': API_KEY}
    )

    decoded = response.json()['decoded']
    return json.loads(decoded)

# Decode a JWT payload
token = "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMjN9.signature"
payload = decode_jwt_payload(token)
print(payload)  # {'user_id': 123}

cURL - Quick Encoding

# Encode
curl "https://api.tinyfn.io/v1/encode/base64/encode?text=secret:password" \
  -H "X-API-Key: $TINYFN_KEY"

# Decode
curl "https://api.tinyfn.io/v1/encode/base64/decode?encoded=c2VjcmV0OnBhc3N3b3Jk" \
  -H "X-API-Key: $TINYFN_KEY"

Handling Unicode

Our API properly handles Unicode characters by encoding them as UTF-8 before Base64 encoding:

GET /v1/encode/base64/encode?text=Hello%20%F0%9F%91%8B

{
  "original": "Hello [emoji]",
  "encoded": "SGVsbG8g8J+Riw==",
  "encoding": "utf-8"
}

Common Pitfalls

1. Padding: Base64 uses = padding to make output length divisible by 4
2. Line breaks: Some implementations add line breaks every 76 characters (MIME)
3. URL encoding: Remember to URL-encode your input text in query parameters
4. Binary data: For binary files, use our POST endpoint instead of GET

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-encode": {
      "url": "https://api.tinyfn.io/mcp/encode/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all encoding tools available via MCP in our Encoding MCP Tools for AI Agents guide.