Stop Leaking Secrets: Decode JWTs Locally on Mac (Safe, No-Upload Methods)

This guide walks through secure, offline methods to decode JSON Web Tokens (JWTs) on macOS so you never have to paste sensitive bearer tokens into a third‑party web tool. It explains simple terminal helpers (bash/zsh), Node and Python scripts, a browser DevTools snippet, and considerations for a native on‑device workflow.

Key takeaways

  • Never paste JWTs into third‑party websites — tokens can be captured and indexed.
  • Use on‑device decoding: DevTools snippet, terminal helper (jq), Node or Python scripts, or a vetted native app.
  • Decoding shows claims but does not verify signatures; signature verification requires the issuer's key and a verification library.

Why you should avoid online JWT decoders

JWTs are bearer tokens: whoever holds the token can present it for access. Public sites that accept pasted tokens can log, index or expose those values. Security researchers reported large-scale scraping of developer snippets on popular formatter sites in late 2025; that investigation found tens of thousands of leaked developer snippets that included administrative tokens, API keys and customer data. Because of that risk, prefer on‑device decoding methods that never send the token off your Mac.

Prerequisites

  • macOS with Terminal access (bash or zsh)
  • jq installed for JSON formatting (install with brew install jq if needed)
  • Node.js or Python available if you plan to use those scripts (optional)
  • Basic familiarity with copying tokens from browser storage or request headers
  • Fast, no‑install: Chrome/Safari DevTools console snippet (runs in the browser, never sends data externally).
  • Terminal helper: Add a small function to ~/.zshrc or ~/.bashrc that decodes and pretty‑prints header and payload using jq.
  • Scripted options: Tiny one‑file decoders in Node or Python for repeated local use.
  • Native on‑device app: Use a vetted macOS native utility that performs decoding locally with no telemetry if you want GUI convenience.

1) Add a terminal helper (zsh/bash + jq)

Purpose: fast terminal decoding, usable from any shell session. This approach keeps tokens on your machine and uses jq to format JSON.

  1. Open ~/.zshrc (or ~/.bashrc) in an editor.
  2. Add this function exactly as shown (paraphrased implementation from community examples):
    <code>decodejwt() {
      echo "$1" | jq -R -s 'gsub("\n"; "") | split(".") | {header: (.[0] | @base64d | fromjson), payload: (.[1] | @base64d | fromjson), signature: .[2]}'
    }
    # Usage: decodejwt "YOUR_JWT_STRING"
    </code>
  3. Reload your shell: source ~/.zshrc or open a new Terminal window.
  4. Run: decodejwt "paste_your_jwt_here". The header and payload print as formatted JSON and the signature appears as raw text.

Notes and edge cases

  • The function assumes standard Base64URL encoding and will fail on malformed tokens.
  • If your token contains newlines or surrounding quotes, wrap it in single quotes or remove whitespace before decoding.
  • jq’s @base64d works in many jq versions; if you encounter errors, confirm your jq version or use the Node/Python scripts below.

2) Node.js one‑liner script

Purpose: platform‑independent local script for Node users that explicitly uses Base64URL handling.

  1. Create a file named decode.js with the following content (keeps decoding local):
    <code>const token = process.argv[2];
    const [header, payload, signature] = token.split('.');
    console.log(JSON.stringify({
      header: JSON.parse(Buffer.from(header, 'base64url').toString()),
      payload: JSON.parse(Buffer.from(payload, 'base64url').toString()),
      signature
    }, null, 2));
    </code>
  2. Run: node decode.js "YOUR_JWT_STRING".

Notes and trade-offs

  • Node’s Buffer supports base64url in modern Node versions; older Node may require a small helper to replace URL‑safe characters and add padding.
  • This script only decodes; it does not verify signatures or validate claims.

3) Python script (handles Base64URL padding)

Purpose: small local script for Python users with explicit Base64 padding handling.

  1. Create decode_jwt.py with these lines:
    <code>import sys, base64, json
    
    def dec(s):
        return json.loads(base64.b64decode(s + '=' * (-len(s) % 4)))
    
    h, p, s = sys.argv[1].split('.')
    print(json.dumps({'header': dec(h), 'payload': dec(p), 'signature': s}, indent=2))
    </code>
  2. Run: python3 decode_jwt.py "YOUR_JWT_STRING".

Notes

  • This uses standard library only. The function pads Base64URL strings so decoding succeeds even when padding has been omitted.
  • Like the Node and jq approaches, it decodes but does not verify cryptographic signatures.

4) Quick browser DevTools snippet (zero files)

Purpose: fastest on‑device method while you’re already inspecting requests—runs inside the browser console and never transmits the token off the client.

  1. Open DevTools (Command+Option+I) and go to the Console tab.
  2. Paste this snippet and call it with your token:
    <code>const decodeJWT = (t) => t.split('.').slice(0,2).map(p => JSON.parse(atob(p.replace(/-/g, '+').replace(/_/g, '/'))));
    console.log(decodeJWT("YOUR_JWT_STRING"));
    </code>

Notes and limitations

  • This runs entirely in the browser; do not run code copied from untrusted pages into DevTools.
  • If your token contains Unicode in the payload, browsers’ atob may mis-handle multi-byte characters—JSON typically uses ASCII for field names/values, but be aware of potential decoding artifacts.

5) Native on‑device tools: convenience vs auditability

Purpose: reduce friction by using a GUI app that detects and decodes tokens from the clipboard without uploading data. Several third‑party native utilities advertise local decoding and clipboard inspection.

  • Benefit: GUI convenience (automatic detection, popup UI, prettified JSON) and usually faster than terminal snippets.
  • Risk/trade-off: pick a vetted app with clear privacy promises (zero telemetry, open source or strong reputation). Do not install untrusted apps that might exfiltrate clipboard contents.

How to evaluate a native app

  1. Prefer open‑source tools so you can inspect network calls and telemetry.
  2. Check the developer’s privacy statement for explicit “on‑device only” or “no telemetry” language.
  3. Monitor outbound network traffic right after installing using Little Snitch or the built‑in Packet Filter to confirm no unexpected connections.

Validation, verification and what these tools do not do

All decoding methods above reveal the header and payload; they do not verify the token’s signature or guarantee the token is valid. To check signature validity you need the appropriate signing key and a verification library (for example, using jsonwebtoken in Node or PyJWT in Python). Only verify signatures in a trusted environment and avoid copying signing keys into temporary tools.

Troubleshooting and common mistakes

  • Malformed token (wrong segment count): A JWT should have three segments separated by dots. If you see a different format, confirm you copied the full token.
  • Base64URL padding errors: Use the Python script or Node’s base64url support; terminal helpers that rely on jq may fail if your jq lacks @base64d.
  • Unicode payload issues in DevTools: If non‑ASCII characters look garbled, use the Node or Python method to preserve multi‑byte characters correctly.
  • Don’t paste tokens into unfamiliar pages: Even “client‑side only” claims can be misleading if the site stores or indexes snippets.

Practical workflow recommendations

  1. For occasional checks: use the DevTools snippet while inspecting network requests.
  2. For repeated use in terminal workflows: add the zsh/bash helper with jq or keep the short Node/Python script in a secure dev utilities folder with restricted file permissions.
  3. For GUI convenience: choose a vetted native app with on‑device guarantees and monitor network traffic after install.
  4. Always treat decoded JWT payloads as sensitive: redact or avoid screenshots, keep token lifetime short in production and rotate tokens if accidental exposure is suspected.

Short FAQ

  • Can these methods verify a JWT? No — decoding shows header and payload but does not cryptographically verify the signature. Verification requires the issuer’s key and a verification library.
  • Is it safe to store decoding scripts in a dotfiles repo? Only if the repository is private and access is controlled. Never commit actual tokens or signing keys.
  • Which approach is fastest? DevTools for ad‑hoc checks; the shell helper or native GUI for repeated use.

Timeline and context

Security researchers disclosed large-scale scraping of developer snippets from online formatting and snippet sites in late 2025, showing how quickly pasted tokens can leak. That incident highlights why on‑device decoding should be the default for developers handling production data.

Closing practical checklist

  1. Never paste production JWTs into third‑party web tools.
  2. Install jq and add the shell helper for quick terminal decoding.
  3. Keep a Node or Python decoder in a secure utilities folder for portable scripts.
  4. If you use a native GUI tool, verify its privacy posture and monitor outbound traffic.
  5. Rotate tokens if you suspect they were exposed.

Use these on‑device methods to keep debugging fast without risking leaked bearer tokens.

Stay in Touch

spot_img

Related Articles