Creating Rules

Create a new rule to define detection, obfuscation, or blocking policies for sensitive data.

---

Endpoint

POST /api/rules

Creates a new rule that defines how Shield processes sensitive data based on applications, user context, and time windows.

---

Authentication

Requires API Key with Policy Definition permission.

---

Request Body

Field	Type	Required	Description
name	string	Yes	Rule name (1-64 chars)
description	string	No	Description (0-128 chars)
action	string	Yes	"detect", "obfuscate", or "block"
enable	boolean	Yes	Whether rule is active (true) or disabled (false)
icapMode	string	No	"REQMOD" (requests), "RESPMOD" (responses), "BOTH" (both), or empty (both)
apps	string[]	Yes	Application UUIDs this rule applies to (at least one required)
obfuscations	string[]	No	Obfuscation UUIDs (required if action is "obfuscate")
userFilters	array	No	User-based filtering - see User Filters
groupFilters	array	No	Group-based filtering - see Group Filters
timeFilterEnabled	boolean	No	Enable time-based filtering (default: false)
timeFilter	object	No	Time window configuration - see Time Filters

User Filters

Apply rules based on username. Each filter object contains:

Field	Type	Required	Description
condition	string	Yes	"equal", "notequal", "contains", "doesnotcontain"
filter	string	Yes	Username or pattern to match

Group Filters

Apply rules based on user's directory group membership. Each filter object contains:

Field	Type	Required	Description
condition	string	Yes	"equal", "notequal", "contains", "doesnotcontain"
filter	string	Yes	Group name or pattern to match
provider	string	No	Directory provider (e.g., "AzureAD", "Okta", "Google")

Time Filters

Apply rules during specific time windows. The timeFilter object contains:

Field	Type	Required	Description
timeWindows	array	Yes	Array of time range objects with startTime and endTime (HH:MM format)
daysOfWeek	integer[]	Yes	Days to apply (0=Sunday, 1=Monday, ..., 6=Saturday)
timezone	string	Yes	IANA timezone (e.g., "America/New_York", "Europe/London")
behavior	string	Yes	"match" (apply during window) or "bypass" (apply outside window)

---

Response

Returns the created rule object with an id field:

Response Format

{
  "id": "rule-uuid-123",
  "name": "Block PII in External APIs",
  "description": "Prevent PII from being sent to third-party services",
  "action": "block",
  "enable": true,
  "icapMode": "REQMOD",
  "apps": ["app-uuid-1", "app-uuid-2"],
  "obfuscations": ["obfuscation-uuid-1"],
  "userFilters": [
    {
      "condition": "notequal",
      "filter": "admin"
    }
  ],
  "groupFilters": [
    {
      "condition": "contains",
      "filter": "Engineering",
      "provider": "AzureAD"
    }
  ],
  "timeFilterEnabled": true,
  "timeFilter": {
    "timeWindows": [
      {
        "startTime": "09:00",
        "endTime": "17:00"
      }
    ],
    "daysOfWeek": [1, 2, 3, 4, 5],
    "timezone": "America/New_York",
    "behavior": "match"
  },
  "createdAt": 1704067200,
  "updatedAt": 1704067200
}

Response Fields

Field	Type	Description
id	UUID	Unique rule identifier
name	string	Rule name
description	string	Rule description
action	string	Action to perform (detect, obfuscate, or block)
enable	boolean	Whether rule is active
icapMode	string	ICAP mode (REQMOD, RESPMOD, BOTH, or empty for both)
apps	string[]	Application UUIDs
obfuscations	string[]	Obfuscation UUIDs
userFilters	array	User-based filters
groupFilters	array	Group-based filters
timeFilterEnabled	boolean	Whether time filtering is enabled
timeFilter	object	Time window configuration
createdAt	integer	Unix timestamp when created
updatedAt	integer	Unix timestamp of last update

---

Examples

Create Detection-Only Rule

Create a rule that detects sensitive data without obfuscating it, useful for auditing and compliance.

cURLPythonNode.js

curl -X POST "https://your-shield-host:8080/api/rules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Detect SSNs in All Apps",
    "description": "Audit all SSN usage for compliance",
    "action": "detect",
    "enable": true,
    "apps": ["app-uuid-1", "app-uuid-2"],
    "icapMode": "REQMOD"
  }'

import requests

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

rule = {
    "name": "Detect SSNs in All Apps",
    "description": "Audit all SSN usage for compliance",
    "action": "detect",
    "enable": True,
    "apps": ["app-uuid-1", "app-uuid-2"],
    "icapMode": "REQMOD"
}

response = requests.post(f"{BASE_URL}/api/rules", headers=HEADERS, json=rule)
rule_id = response.json()["id"]
print(f"Created rule: {rule_id}")

const axios = require('axios');

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

const rule = {
  name: 'Detect SSNs in All Apps',
  description: 'Audit all SSN usage for compliance',
  action: 'detect',
  enable: true,
  apps: ['app-uuid-1', 'app-uuid-2'],
  icapMode: 'REQMOD'
};

const response = await axios.post(`${BASE_URL}/api/rules`, rule, { headers: HEADERS });
const ruleId = response.data.id;
console.log(`Created rule: ${ruleId}`);

Create Obfuscation Rule with Time Filter

Mask credit cards during business hours only.

cURLPythonNode.js

curl -X POST "https://your-shield-host:8080/api/rules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mask Credit Cards During Business Hours",
    "description": "Obfuscate credit cards during business hours",
    "action": "obfuscate",
    "enable": true,
    "apps": ["payment-app-uuid"],
    "obfuscations": ["credit-card-obf-uuid"],
    "timeFilterEnabled": true,
    "timeFilter": {
      "timeWindows": [{"startTime": "08:00", "endTime": "18:00"}],
      "daysOfWeek": [1, 2, 3, 4, 5],
      "timezone": "America/Los_Angeles",
      "behavior": "match"
    }
  }'

import requests

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

rule = {
    "name": "Mask Credit Cards During Business Hours",
    "description": "Obfuscate credit cards during business hours",
    "action": "obfuscate",
    "enable": True,
    "apps": ["payment-app-uuid"],
    "obfuscations": ["credit-card-obf-uuid"],
    "timeFilterEnabled": True,
    "timeFilter": {
        "timeWindows": [{"startTime": "08:00", "endTime": "18:00"}],
        "daysOfWeek": [1, 2, 3, 4, 5],
        "timezone": "America/Los_Angeles",
        "behavior": "match"
    }
}

response = requests.post(f"{BASE_URL}/api/rules", headers=HEADERS, json=rule)
rule_id = response.json()["id"]
print(f"Created rule: {rule_id}")

const axios = require('axios');

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

const rule = {
  name: 'Mask Credit Cards During Business Hours',
  description: 'Obfuscate credit cards during business hours',
  action: 'obfuscate',
  enable: true,
  apps: ['payment-app-uuid'],
  obfuscations: ['credit-card-obf-uuid'],
  timeFilterEnabled: true,
  timeFilter: {
    timeWindows: [{ startTime: '08:00', endTime: '18:00' }],
    daysOfWeek: [1, 2, 3, 4, 5],
    timezone: 'America/Los_Angeles',
    behavior: 'match'
  }
};

const response = await axios.post(`${BASE_URL}/api/rules`, rule, { headers: HEADERS });
const ruleId = response.data.id;
console.log(`Created rule: ${ruleId}`);

Create Rule with User and Group Filters

Block PII for non-admin users in the Engineering group.

cURLPythonNode.js

curl -X POST "https://your-shield-host:8080/api/rules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block PII for Engineering Non-Admins",
    "description": "Prevent PII access for non-admin engineers",
    "action": "block",
    "enable": true,
    "apps": ["hr-system-uuid"],
    "obfuscations": ["pii-obf-uuid"],
    "userFilters": [
      {
        "condition": "notequal",
        "filter": "admin"
      }
    ],
    "groupFilters": [
      {
        "condition": "contains",
        "filter": "Engineering",
        "provider": "AzureAD"
      }
    ]
  }'

import requests

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

rule = {
    "name": "Block PII for Engineering Non-Admins",
    "description": "Prevent PII access for non-admin engineers",
    "action": "block",
    "enable": True,
    "apps": ["hr-system-uuid"],
    "obfuscations": ["pii-obf-uuid"],
    "userFilters": [
        {
            "condition": "notequal",
            "filter": "admin"
        }
    ],
    "groupFilters": [
        {
            "condition": "contains",
            "filter": "Engineering",
            "provider": "AzureAD"
        }
    ]
}

response = requests.post(f"{BASE_URL}/api/rules", headers=HEADERS, json=rule)
print(f"Created rule: {response.json()['id']}")

const axios = require('axios');

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

const rule = {
  name: 'Block PII for Engineering Non-Admins',
  description: 'Prevent PII access for non-admin engineers',
  action: 'block',
  enable: true,
  apps: ['hr-system-uuid'],
  obfuscations: ['pii-obf-uuid'],
  userFilters: [
    {
      condition: 'notequal',
      filter: 'admin'
    }
  ],
  groupFilters: [
    {
      condition: 'contains',
      filter: 'Engineering',
      provider: 'AzureAD'
    }
  ]
};

const response = await axios.post(`${BASE_URL}/api/rules`, rule, { headers: HEADERS });
console.log(`Created rule: ${response.data.id}`);

---

Error Responses

Status Code	Description	Solution
400	Invalid request body or validation error	Check field validation requirements
401	Invalid or expired API key	Verify authentication
403	Insufficient permissions	Key needs Policy Definition permission
409	Rule name already exists	Use a unique name or update the existing rule

---

Related Topics

• List Rules - Query all rules
• Update Rules - Modify existing rules
• Reorder Rules - Adjust rule evaluation priority
• Applications API - Create applications to reference in rules
• Obfuscations API - Create obfuscations for masking data