Skip to content

Obfuscations Reference

Detailed reference information for the Obfuscations API.

Field Validation

Name

Field Constraints
Length 1-64 characters
Format Any printable characters

Description

Field Constraints
Length 0-128 characters
Format Any printable characters

Filter Conditions

Obfuscations can use contextual filters to apply masking conditionally based on surrounding data.

Number Condition

Match numeric values with comparison operators.

{
  "numberCondition": {
    "operator": "greaterThan",
    "value": 1000.00
  }
}

Operators: equal, notEqual, greaterThan, lessThan, greaterThanOrEqual, lessThanOrEqual

String Condition

Match string values with text operators.

{
  "stringCondition": {
    "operator": "contains",
    "value": "test"
  }
}

Operators: equal, notEqual, contains, notContains, startsWith, endsWith

Date Condition

Match date values with temporal operators.

{
  "dateCondition": {
    "operator": "before",
    "value": "2026-12-31T00:00:00Z"
  }
}

Operators: before, after, between

Filter Types

ID Name Description
0 Sibling Match field at same level
1 Parent Match field in parent object
2 Ancestor Match field in ancestor object

Mask Format Types

Common mask formats available in Shield:

Format Description Example
Asterisk Replace with asterisks ***-**-1234
Hash One-way SHA256 hash a3f8b9c2d1e0f4a5...
Last 4 Show only last 4 characters ****1234
First 4 Show only first 4 characters 1234****
Redact Replace with placeholder [REDACTED]
Tokenize Replace with reversible token tok_a3f8b9c2
Email Mask Mask email preserving domain u***@example.com

Query available formats: GET /api/maskformats

Store Original Value

When to Enable

Enable storeOriginalValue when:

  • De-obfuscation is required for authorized users
  • Audit trails need original values
  • Compliance requires retaining original data
  • Analytics need access to real values

When to Disable

Disable storeOriginalValue when:

  • Data is permanently masked
  • Storage efficiency is critical
  • Compliance prohibits retention
  • No de-obfuscation needed

Security Implications

When enabled:

  • Original values are encrypted before storage
  • Encryption keys are managed by Shield
  • Access requires proper authorization
  • Storage size increases proportionally

Whitelist Best Practices

Test Data

Exclude known test values:

{
  "whitelist": [
    "000-00-0000",
    "111-11-1111",
    "123-45-6789"
  ]
}

Placeholder Values

Exclude placeholder or example values:

{
  "whitelist": [
    "xxx-xx-xxxx",
    "N/A",
    "Unknown"
  ]
}

System Values

Exclude system-generated values that aren't sensitive:

{
  "whitelist": [
    "SYSTEM",
    "AUTO-GENERATED",
    "DEFAULT"
  ]
}

Filter Examples

High-Value Transaction Filter

Only mask when amount exceeds threshold:

Example 
{
  "filters": [
    {
      "type": "amount",
      "filterType": 1,
      "filterParentLevel": 0,
      "isWhitelist": false,
      "condition": {
        "numberCondition": {
          "operator": "greaterThan",
          "value": 10000.00
        }
      }
    }
  ]
}

Environment-Based Filter

Mask in production, not in development:

Response Format 
{
  "filters": [
    {
      "type": "environment",
      "filterType": 0,
      "isWhitelist": false,
      "condition": {
        "stringCondition": {
          "operator": "equal",
          "value": "production"
        }
      }
    }
  ]
}

Date Range Filter

Only mask recent transactions:

Response Format 
{
  "filters": [
    {
      "type": "transaction_date",
      "filterType": 1,
      "isWhitelist": false,
      "condition": {
        "dateCondition": {
          "operator": "after",
          "value": "2026-01-01T00:00:00Z"
        }
      }
    }
  ]
}

Best Practices

  • Store originals carefully - Only enable storeOriginalValue when de-obfuscation is required
  • Use whitelists for test data - Exclude known test values from masking
  • Name descriptively - Indicate which data types and formats are used
  • Test filters thoroughly - Contextual filters can be complex - verify with real data
  • Group related types - Combine multiple data types in one obfuscation when they share the same mask format
  • Document filters - Use description field to explain complex filter logic
  • Monitor performance - Complex filters may impact scanning performance