Skip to content

Dynamic Scanning

Scan content with explicit control over data type detection and masking.

Overview

The /api/scan-dynamic endpoint provides explicit control over which data types to detect and how to mask them, bypassing configured policies. This is useful for:

  • Testing mask formats
  • Custom workflows requiring different masking per scenario
  • Scanning specific data types without creating policies
  • Temporary or one-off scanning requirements

Authentication

Requires API Key with Data Scanning permission.

Authorization: Bearer <your-api-key>

How It Works

Unlike /api/scan, which applies configured policies, /api/scan-dynamic lets you specify:

  1. Exact data types to detect (by type identifier, e.g., US_SSN, CREDIT_CARD)
  2. Specific mask formats to apply (by mask format ID)
  3. Whether to store original values for de-obfuscation
  4. Namespace, username, usergroup for logging only (does not affect masking)

Endpoint

POST /api/scan-dynamic

Scan content with explicit data type and mask format control.

Request

POST /api/scan-dynamic?namespace=<app>&obfuscatedDataTypes=<types>&maskFormats=<formats>&storeOriginalValues=<bool>
Content-Type: application/json
Authorization: Bearer <api-key>

Query Parameters

Parameter Required Description
namespace Yes Application identifier (for logging only)
obfuscatedDataTypes Yes Comma-separated data type identifiers to detect and mask (e.g., US_SSN,CREDIT_CARD)
maskFormats No Comma-separated mask format IDs (matches types in order, e.g., FULLY_OBFUSCATED,LEAVE_LAST_FOUR)
storeOriginalValues No Store originals for de-obfuscation (true/false, default: false)
username No Username for activity logging
usergroup No User group for activity logging

Request Body

Any content type is supported (JSON, XML, text, etc.). The response will be in the same format as the request.

Getting Data Type and Mask Format Identifiers

Before using /api/scan-dynamic, you need to get the type identifiers for data types and IDs for mask formats.

Get Data Type Identifiers 
# List all data types and their identifiers
curl -X GET "https://your-shield-host:8080/api/datatypes" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.items[] | {type, name}'

# The 'type' field is the identifier you use in scan-dynamic
# Example output: {"type": "US_SSN", "name": "US Social Security Number"}

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Get all data types
response = requests.get(f"{BASE_URL}/api/datatypes", headers=HEADERS)
datatypes = response.json()["items"]

# The 'type' field is what you use in scan-dynamic
for dt in datatypes:
    print(f"{dt['type']}: {dt['name']}")

# Examples: US_SSN, CREDIT_CARD, EMAIL_ADDRESS, PHONE_NUMBER

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

// Get all data types
const response = await axios.get(
  `${BASE_URL}/api/datatypes`,
  { headers: HEADERS }
);

const datatypes = response.data.items;

// The 'type' field is what you use in scan-dynamic
datatypes.forEach(dt => {
  console.log(`${dt.type}: ${dt.name}`);
});

// Examples: US_SSN, CREDIT_CARD, EMAIL_ADDRESS, PHONE_NUMBER

Examples

Scan Specific Data Type

Scan for SSN only, using FULLY_OBFUSCATED masking.

# Scan with US_SSN data type and FULLY_OBFUSCATED mask format
curl -X POST "https://your-shield-host:8080/api/scan-dynamic?namespace=api&obfuscatedDataTypes=US_SSN&maskFormats=FULLY_OBFUSCATED" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {
      "name": "John Doe",
      "ssn": "123-45-6789",
      "email": "test@example.com"
    }
  }'

# Response:
# {
#   "person": {
#     "name": "John Doe",
#     "ssn": "***********",
#     "email": "test@example.com"
#   }
# }

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Scan data - use data type identifier directly
data = {
    "person": {
        "name": "John Doe",
        "ssn": "123-45-6789",
        "email": "test@example.com"
    }
}

response = requests.post(
    f"{BASE_URL}/api/scan-dynamic",
    headers=HEADERS,
    params={
        "namespace": "api",
        "obfuscatedDataTypes": "US_SSN",
        "maskFormats": "FULLY_OBFUSCATED"
    },
    json=data
)

print(response.json())
# Output: {'person': {'name': 'John Doe', 'ssn': '***********', 'email': 'test@example.com'}}

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

// Scan data - use data type identifier directly
const data = {
  person: {
    name: 'John Doe',
    ssn: '123-45-6789',
    email: 'test@example.com'
  }
};

const response = await axios.post(
  `${BASE_URL}/api/scan-dynamic`,
  data,
  {
    headers: HEADERS,
    params: {
      namespace: 'api',
      obfuscatedDataTypes: 'US_SSN',
      maskFormats: 'FULLY_OBFUSCATED'
    }
  }
);

console.log(response.data);

Response: (only SSN is masked, email untouched)

{
  "ssn": "*********",
  "email": "test@example.com"
}
Scan Multiple Data Types

Scan for both SSN and credit card with different mask formats.

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Scan with multiple data types
data = {
    "ssn": "123-45-6789",
    "creditCard": "4532-1234-5678-9012",
    "name": "John Doe"
}

response = requests.post(
    f"{BASE_URL}/api/scan-dynamic",
    headers=HEADERS,
    params={
        "namespace": "api",
        "obfuscatedDataTypes": "US_SSN,CREDIT_CARD",
        "maskFormats": "FULLY_OBFUSCATED,LEAVE_LAST_FOUR"  # SSN=fully masked, CC=show last 4
    },
    json=data
)

print(response.json())

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

// Scan with multiple data types
const data = {
  ssn: '123-45-6789',
  creditCard: '4532-1234-5678-9012',
  name: 'John Doe'
};

const response = await axios.post(
  `${BASE_URL}/api/scan-dynamic`,
  data,
  {
    headers: HEADERS,
    params: {
      namespace: 'api',
      obfuscatedDataTypes: 'US_SSN,CREDIT_CARD',
      maskFormats: 'FULLY_OBFUSCATED,LEAVE_LAST_FOUR'  // SSN=fully masked, CC=show last 4
    }
  }
);

console.log(response.data);

Response:

{
  "ssn": "*********",
  "creditCard": "****-****-****-9012",
  "name": "John Doe"
}
Store Original Values

Scan with ability to de-obfuscate later.

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Get SSN ID
datatypes = requests.get(f"{BASE_URL}/api/datatypes", headers=HEADERS).json()["items"]
ssn_id = next(d["id"] for d in datatypes if d["type"] == "US_SSN")

# Scan with storage enabled
data = {"ssn": "123-45-6789"}

response = requests.post(
    f"{BASE_URL}/api/scan-dynamic",
    headers=HEADERS,
    params={
        "namespace": "api",
        "obfuscatedDataTypes": ssn_id,
        "storeOriginalValues": "true"
    },
    json=data
)

print(response.json())
# Original value is now stored in Shield and can be de-obfuscated

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

// Get SSN ID
const datatypesResp = await axios.get(`${BASE_URL}/api/datatypes`, { headers: HEADERS });
const ssnId = datatypesResp.data.items.find(d => d.type === 'US_SSN').id;

// Scan with storage enabled
const data = { ssn: '123-45-6789' };

const response = await axios.post(
  `${BASE_URL}/api/scan-dynamic`,
  data,
  {
    headers: HEADERS,
    params: {
      namespace: 'api',
      obfuscatedDataTypes: ssnId,
      storeOriginalValues: 'true'
    }
  }
);

console.log(response.data);
// Original value is now stored in Shield and can be de-obfuscated

Response

The response format matches the request content type. Only specified data types are masked.

Response Fields:

  • Original structure is preserved
  • Specified data types are obfuscated
  • Other data remains unchanged