API Auth Debugging: JWT → JSON → Hash
Debug API authentication failures step by step: decode the JWT token, format the JSON payload, then verify credential hashes. A complete workflow for API developers.
The Problem
Your API returns 401 or 403 errors and you need to trace the exact failure. Is the JWT malformed? Has the token expired? Is the user ID in the payload wrong? Does the stored password hash match? These checks normally require running code — this workflow lets you do all three in under two minutes.
Why This Matters
Authentication bugs are among the most frustrating to debug because errors are intentionally vague for security reasons. A systematic three-step workflow — decode the token structure, inspect the JSON claims, verify the hash — pinpoints the exact failure without deploying debug code or exposing credentials.
Step-by-Step Instructions
Decode the JWT to expose the payload
Copy the JWT from your Authorization header or logs. Paste it into the JWT Decoder. Inspect sub (user ID), exp (expiry timestamp), iss (issuer), and any custom claims. Confirm the token hasn't expired and contains expected values.
Format the payload JSON for easier reading
Copy the decoded payload object and paste it into the JSON Formatter. Pretty-print it with indentation so you can clearly see nested claims, role arrays, or permission scopes. Look for missing fields that your API expects.
Verify password or API key hash
If credentials are the issue, use the Hash Generator to compute SHA-256 of the password or API key. Compare with the stored hash in your database. A mismatch confirms a credentials problem rather than a token problem.
Cross-check expiry with current time
The JWT Decoder converts exp to a human-readable timestamp. If it shows as expired, your client isn't refreshing tokens correctly. Check if your token refresh logic fires before the exp time.
Try It Now — JWT Decoder
Open full page →All processing happens in your browser — no data is sent to any server.
Before & After Example
HTTP 401 Unauthorized Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzQ1NiIsInJvbGUiOiJ2aWV3ZXIiLCJpYXQiOjE3MDk4MDAwMDAsImV4cCI6MTcwOTgwMzYwMH0.abc123 # You have no idea why it's failing
{
"sub": "user_456",
"role": "viewer", // ← needs "admin" for this endpoint
"iat": 1709800000, // Issued: 2026-03-07 10:00
"exp": 1709803600 // Expires: 2026-03-07 11:00 ✓ valid
}
# Root cause: user has "viewer" role, endpoint requires "admin"
Frequently Asked Questions
What is the most common cause of 401 vs 403 errors?
401 means the token is missing, expired, or invalid — authentication failed. 403 means the token is valid but the user lacks permission for the resource — the role or scope claim doesn't grant access. Decoding the JWT immediately tells you which problem you have.
Which hash algorithm should I use for password storage?
Never use MD5 or SHA-1 for passwords — use bcrypt, scrypt, or Argon2. SHA-256 from the Hash Generator is useful for verifying file integrity, API key hashes, or webhook signatures, not for user passwords.
How do I debug JWT issues in production without exposing tokens?
Use short-lived test tokens with fake user IDs. Copy only the header and payload (first two segments) if you're worried about signature exposure — the decoder only needs those to show claims.
Related Workflows
Try all 3 tools in this workflow
Each tool is free, runs in your browser, and requires no signup.