Skip to content

Obfuscations API

The Obfuscations API allows you to configure how Shield masks or transforms sensitive data when detected.

Overview

Obfuscations define:

  • Which data types to mask
  • Which mask format to apply to each type
  • Whether to store original values for de-obfuscation
  • Whitelists of values to exclude from masking
  • Contextual filters to apply masking conditionally

Obfuscations are referenced by Rules to specify masking behavior.

Authentication

Requires API Key with:

  • Read access: GET operations (all keys)
  • Policy Definition permission: POST, PUT, PATCH, DELETE operations

Available Endpoints

The Obfuscations API provides the following endpoints:

Core Operations

Key Concepts

Data Type Configuration

Each obfuscation contains configurations for one or more data types:

{
  "name": "Mask PII",
  "datatypes": [
    {
      "type": "US_SSN",
      "maskFormatId": "FULLY_OBFUSCATED",
      "storeOriginalValue": true,
      "whitelist": ["000-00-0000"]
    }
  ]
}

Mask Formats

Mask formats determine how sensitive data is transformed. Built-in formats:

Format Identifier Description Example Input Example Output
FULLY_OBFUSCATED Replace all characters with * 123-45-6789 ***********
LEAVE_LAST_FOUR Show only last 4 characters 123-45-6789 *******6789
EMAIL_LEAVE_DOMAIN Mask email username, keep domain user@company.com ****@company.com
EMAIL_HIDE_DOMAIN Mask email domain, keep username user@company.com user@*******.***
LEAVE_SUBDOMAIN Mask URL but leave subdomain api.company.com api.*******
HIDE_SUBDOMAIN Mask subdomain in URLs api.company.com ***.company.com
MD5 Replace with MD5 hash secret123 1f32aa4c9a1d2ea010adcf2348166a04
SHA256 Replace with SHA256 hash secret123 2bb80d537...
SHA1 Replace with SHA1 hash secret123 2f67db8c...
DETECT_ONLY Detect but don't mask (NOOP) 123-45-6789 123-45-6789
BOOLEAN_TRUE Always returns true Any value true
BOOLEAN_FALSE Always returns false Any value false

You can also create custom mask formats with specific patterns and replacement rules.

Store Original Values

When storeOriginalValue is enabled:

  • Original values are encrypted and stored
  • Can be retrieved for authorized users
  • Enables de-obfuscation functionality
  • Increases storage requirements

Whitelists

Exclude specific values from masking:

{
  "whitelist": [
    "000-00-0000",  // Test SSN
    "999-99-9999"   // Another test value
  ]
}

Contextual Filters

Apply masking conditionally based on surrounding data:

{
  "filters": [
    {
      "type": "amount",
      "filterType": 1,
      "condition": {
        "numberCondition": {
          "operator": "greaterThan",
          "value": 10000.00
        }
      }
    }
  ]
}

Common Use Cases

Mask All PII

Create a single obfuscation to mask multiple data types:

{
  "name": "Mask All PII",
  "datatypes": [
    {"type": "US_SSN", "maskFormatId": "FULLY_OBFUSCATED"},
    {"type": "CREDIT_CARD", "maskFormatId": "LEAVE_LAST_FOUR"},
    {"type": "US_PHONE_NUMBER", "maskFormatId": "FULLY_OBFUSCATED"}
  ]
}

Preserve for Audit

Store original values for compliance and audit trails:

{
  "name": "Mask with Audit Trail",
  "datatypes": [
    {
      "type": "US_SSN",
      "maskFormatId": "FULLY_OBFUSCATED",
      "storeOriginalValue": true
    }
  ]
}

Conditional Masking

Mask data only when certain conditions are met:

{
  "name": "Mask High-Value Transactions",
  "datatypes": [{"type": "US_SSN", "maskFormatId": "FULLY_OBFUSCATED"}],
  "filters": [
    {
      "type": "amount",
      "filterType": 1,
      "condition": {"numberCondition": {"operator": "greaterThan", "value": 10000}}
    }
  ]
}

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