10 min
Base64 Encoding: When and Why to Use It
Learn what Base64 encoding is, how it works, and when to use it. Understand the difference between encoding and encryption, common use cases, and best practices for web development.
Loading...
Master API debugging by learning to decode Base64 payloads and inspect JWT tokens. Troubleshoot authentication issues, read encoded error messages, and understand what your APIs are actually sending and receiving.
I was staring at a 401 Unauthorized response for two hours. The token looked fine. The API endpoint was correct. Everything should have worked. Then I finally decoded the JWT and saw it: the token had expired 3 minutes ago. Three minutes.
That morning taught me something I now tell every developer at Šikulovi s.r.o.: when you're debugging APIs, your first move should always be decoding. JWTs, Base64 payloads, encoded error messages - there's usually critical information hiding in plain sight, just scrambled.
After years of API work, I've trained my eyes to recognize encoded data patterns. Here's what I look for:
These are the situations where I reach for my decoder tools. If you recognize the pattern, you'll solve it faster:
I've tried every method. Here's what I actually use day-to-day:
A JWT has three parts separated by dots: header.payload.signature. The first two are just Base64-encoded JSON - you can read them. The signature? That's cryptographic gibberish, don't bother.
Here's my mental model: header tells you HOW it's signed, payload tells you WHO and WHEN, signature proves it wasn't tampered with.
When a JWT isn't working, I have a mental checklist. In order of how often they're the problem:
Here's my exact process when I suspect expiration:
Signature failures are trickier. Usually it's one of these:
Some APIs hide detailed errors in Base64. I've found gold in headers like X-Error-Details and WWW-Authenticate. Always try decoding anything that looks like Base64 in an error response - you might find the actual stack trace or validation message.
OAuth flows have tokens everywhere. Here's where to look:
I keep browser DevTools open constantly during API work. Here's my routine:
When I'm already in terminal, these save time:
Webhooks are tricky because the signature must match EXACTLY. I've wasted hours on these:
When decoding fails, it's usually one of these:
When auth fails and I need to be systematic, this is my exact process:
Be careful where you paste tokens. Production JWTs contain real user data. I only use CodeUtil's decoder or local tools for production tokens - never random online decoders. Even expired tokens are sensitive.
After that 2-hour 401 debugging session, I built decoding into my default workflow. Now I decode first, ask questions later. It's saved me countless hours at Šikulovi s.r.o..
Keep decoder tools readily available, understand JWT claim structure, and follow a methodical approach to troubleshooting. These skills reduce debugging time and help you resolve API issues with confidence.
Split the JWT by dots to get three parts. The first two parts (header and payload) are Base64URL-encoded JSON. In JavaScript: JSON.parse(atob(token.split(".")[1])) decodes the payload. In the terminal: echo "token" | cut -d. -f2 | base64 --decode. The third part (signature) cannot be meaningfully decoded—it is cryptographic data.
Usually: expired token (check exp), wrong audience (aud), clock skew, or rotated keys. Decode the token first - 90% of the time the answer is right there in the claims.
Base64URL replaces + with - and / with _ to make tokens URL-safe. JWTs use Base64URL. If standard decoding fails, try replacing those characters first.
Look for strings with only letters, numbers, +, /, and =. Length is always divisible by 4. When in doubt, try decoding it - you'll know immediately if it works.
That's a Unix timestamp (seconds since 1970). Convert with new Date(exp * 1000) in JavaScript. Compare to Date.now()/1000 to see if it's expired.
You can decode and view JWT contents, but modifying any part invalidates the signature. The server will reject altered tokens. For debugging, generate new tokens with the desired claims through your authentication system. If you need to test specific claim values, use your auth server's admin tools or test token generation endpoint.
Use the exact raw body bytes - don't parse and re-serialize JSON. Check the algorithm (usually HMAC-SHA256) and verify your secret hasn't rotated.
Terminal: base64 --decode. Browser: atob(). For JWTs specifically, jwt-cli is handy. For sensitive tokens, always use local tools, never paste into random websites.
Founder of CodeUtil. Web developer building tools I actually use. When I'm not coding, I experiment with productivity techniques (with mixed success).
Learn what Base64 encoding is, how it works, and when to use it. Understand the difference between encoding and encryption, common use cases, and best practices for web development.
After years of staring at regex patterns that should work but don't, I developed a systematic debugging approach. Here's my step-by-step method for finding and fixing regex bugs.
Learn how JWT claims work, explore registered, public, and private claims, and discover security best practices for implementing JSON Web Tokens in your applications.