Redact / sanitize JSON (remove secrets safely)

Redacting JSON means replacing sensitive values with safe placeholders before the data is shared, logged or used as a test fixture. Good redaction removes the risk while keeping the document useful: the structure stays the same, types stay the same, and relationships between records are still visible. This guide shows patterns that achieve that.

Principles

1. Keep the structure. Don't delete keys if the bug might depend on them being present. Replace the value instead.
2. Keep the type. Replace strings with strings and numbers with numbers. Swapping a number for "REDACTED" can hide type-related bugs or cause new ones.
3. Keep relationships. If userId and ownerId hold the same value, the redacted versions should also match, so you can still tell that the same user owns the record.
4. Make placeholders obvious. Anyone reading the data should immediately see what was replaced, so nobody mistakes a placeholder for real data.

Example

Before:

json
{
  "email": "asha.k@realcompany.com",
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiJ9.abc",
  "address": {
    "line1": "500 Main St",
    "zip": "78701"
  }
}

After:

json
{
  "email": "REDACTED_EMAIL",
  "token": "REDACTED_TOKEN",
  "address": {
    "line1": "REDACTED",
    "zip": "REDACTED"
  }
}

Pattern: consistent pseudonyms

When the same value appears in several places, map each real value to a stable placeholder:

json
{ "userId": "USER_001", "ownerId": "USER_001", "approverId": "USER_002" }

You can still see that the owner and the user are the same person, and that the approver is someone else. Keep the mapping out of the shared copy.

Pattern: keep the format, change the content

Sometimes a value's format matters for debugging, for example when validation rejects a malformed email. Keep the shape but use reserved or fake values:

• Emails: user1@example.com (the example.com domain is reserved for documentation)
• Phone numbers: +1-555-0100 to +1-555-0199 (reserved for fiction in North America)
• IP addresses: 192.0.2.10 (reserved for documentation by RFC 5737)
• Card numbers: well-known test numbers such as 4242 4242 4242 4242
• Numeric IDs: replace with a different number of the same length, for example { "accountId": 111111 } instead of { "accountId": 123456 }

Pattern: partial masking

For values people need to recognize but not read in full, keep a few characters:

json
{ "card": "**** **** **** 4242", "email": "a***@example.com", "apiKey": "sk_live_****9f2a" }

Showing the last few characters of a key is often enough to tell which key was used, without revealing it.

Redacting with jq

jq can redact specific fields everywhere in a document. This replaces every email, token and password value at any depth:

bash
jq 'walk(if type == "object" then
  with_entries(if (.key | test("^(email|token|password)$"; "i"))
               then .value = "REDACTED" else . end)
else . end)' input.json

Run it on a copy and review the output. Field names vary (e_mail, accessToken, secret), so a block list never catches everything on the first try.

What to look for

Check all of these, including nested objects and arrays:

• Credentials: tokens, API keys, passwords, cookies, private keys, signed URLs
• Personal data: names, emails, phone numbers, addresses, birth dates, IP addresses
• Financial data: card and bank account numbers
• Free-text fields such as notes, description and message, where people paste anything
• Encoded values: JWTs and Base64 strings that decode to readable data

Verify before sharing

After redacting, search the output for @, eyJ (the start of most JWTs), Bearer, sk_ and key, and scan it in the JSON Formatter tree view. For more habits that prevent leaks, see JSON privacy & safety tips.