Base64url vs base64: troubleshooting checklist for API requests

Base64URL quick map

Focus for this query

• Normalize alphabet ('-'/'_' vs '+'/'/').
• Add or remove '=' padding based on your target format.
• Validate with local tools before passing payload to your app.

Safe decode workflow

1. Remove whitespace/newlines.
2. Normalize alphabet: -→+, _→/.
3. Add padding so length % 4 == 0.
4. Decode locally and validate output shape (JSON/text/binary).

Runtime snippet (generic)

function base64urlToBase64(input) {
  const s = String(input || '').replace(/\s+/g, '').replace(/-/g, '+').replace(/_/g, '/');
  return s + '='.repeat((4 - (s.length % 4)) % 4);
}

const b64 = base64urlToBase64(token);
const bytes = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
const text = new TextDecoder().decode(bytes);
console.log(text);

Frequent failures

• Invalid character from copy/paste noise or wrong alphabet.
• Missing padding when decoder expects canonical Base64.
• JSON parse after decode fails when payload is not JSON/text.

Privacy guardrail

Base64/Base64URL strings can still contain secrets. Decode locally, redact sensitive fields, and only then share snippets.

FAQ

Is anything uploaded to a server? No. All processing happens locally in your browser. Files are never uploaded.

What is the recommended workflow? Validate the input, fix the first real issue, validate again, then export/convert. This avoids compounding errors.