Skip to content

Data Scanning API

Integration guide for real-time data protection via API.

Overview

Shield provides two scanning endpoints for programmatic data protection:

Endpoint Use Case
/api/scan Apply your configured rules automatically (policy-based)
/api/scan-dynamic Specify exact data types to mask (explicit control)

Both endpoints:

  • Accept any content type (JSON, XML, text, etc.)
  • Return obfuscated content in the same format
  • Generate activity logs for auditing
  • Require API Key with Data Scanning permission

Authentication

Authorization: Bearer <your-api-key>

Requires an API Key with Data Scanning permission. See Generating API Keys for setup.

Available Endpoints

Scanning Operations

  • Policy-Based Scan - POST /api/scan - Automatically apply configured policies
  • Dynamic Scan - POST /api/scan-dynamic - Explicitly control data type detection and masking

Reference

  • Reference - Error handling, performance tips, best practices

Key Concepts

Policy-Based Scanning

The /api/scan endpoint uses Shield's configured policies:

  1. Namespace matching - Match against Application URL filters
  2. Rule application - Apply Rules based on user/group/time
  3. Data type detection - Detect data types from Obfuscations
  4. Mask application - Apply configured mask formats
  5. Activity logging - Log all scans for auditing

Best for: Production environments where policies are centrally managed

Dynamic Scanning

The /api/scan-dynamic endpoint provides explicit control:

  1. Direct specification - Specify exact data types to detect
  2. Custom masking - Choose specific mask formats
  3. Bypass policies - Ignore configured rules
  4. Flexible control - Different masking for different scenarios

Best for: Custom workflows, testing, scenario-specific masking

How Scanning Works

┌─────────────────┐
│  Send Request   │
│  with Content   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Shield Scans   │
│  & Obfuscates   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Return Masked   │
│    Content      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Log Activity   │
└─────────────────┘

Quick Start

Policy-Based Scan Example

curl -X POST "https://shield:8080/api/scan?namespace=payment-api&username=john.doe" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "John Doe",
      "ssn": "123-45-6789",
      "creditCard": "4532-1234-5678-9012"
    }
  }'

Response:

{
  "customer": {
    "name": "John Doe",
    "ssn": "***-**-6789",
    "creditCard": "****-****-****-9012"
  }
}

Dynamic Scan Example

# First get data type IDs
SSN_ID=$(curl -s "https://shield:8080/api/datatypes" \
  -H "Authorization: Bearer $API_KEY" | \
  jq -r '.items[] | select(.type=="ssn") | .id')

# Then scan with explicit data type
curl -X POST "https://shield:8080/api/scan-dynamic?namespace=api&obfuscatedDataTypes=$SSN_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ssn": "123-45-6789",
    "email": "test@example.com"
  }'

Response: (only SSN is masked)

{
  "ssn": "*********",
  "email": "test@example.com"
}