List Firewall Rules

List Firewall Rules

Returns all firewall rules for the authenticated user, ordered by priority (highest first).

Endpoint

GET /v1/firewall-rules

Query Parameters

None. This endpoint returns all rules for the authenticated user.

Examples

TypeScript

import Tokenrouter from 'tokenrouter';

const client = new Tokenrouter({
  apiKey: process.env.TOKENROUTER_API_KEY
});

const response = await client.firewallRules.list();

// Rules are ordered by priority (highest first)
response.data.forEach(rule => {
  console.log(`${rule.name} (Priority: ${rule.priority})`);
  console.log(`  Scope: ${rule.scope}`);
  console.log(`  Type: ${rule.type}`);
  console.log(`  Action: ${rule.action}`);
  console.log(`  Pattern: ${rule.pattern}`);
  console.log(`  Enabled: ${rule.is_enabled}`);
  console.log('---');
});

Python

from tokenrouter import Tokenrouter

client = Tokenrouter(
    api_key=os.getenv("TOKENROUTER_API_KEY")
)

response = client.firewall_rules.list()

# Rules are ordered by priority (highest first)
for rule in response.data:
    print(f"{rule.name} (Priority: {rule.priority})")
    print(f"  Scope: {rule.scope}")
    print(f"  Type: {rule.type}")
    print(f"  Action: {rule.action}")
    print(f"  Pattern: {rule.pattern}")
    print(f"  Enabled: {rule.is_enabled}")
    print("---")

cURL

curl https://api.tokenrouter.io/v1/firewall-rules \
  -H "Authorization: Bearer tr_..."

Response

{
  "data": [
    {
      "id": 123,
      "user_id": 456,
      "name": "Block Credit Cards",
      "is_enabled": true,
      "priority": 100,
      "scope": "prompt",
      "type": "regex",
      "pattern": "\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}",
      "action": "block",
      "replacement": null,
      "created_at": "2025-11-10T12:00:00Z",
      "updated_at": "2025-11-10T12:00:00Z"
    },
    {
      "id": 124,
      "user_id": 456,
      "name": "Mask Email Addresses",
      "is_enabled": true,
      "priority": 80,
      "scope": "response",
      "type": "regex",
      "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
      "action": "mask",
      "replacement": "[EMAIL_REDACTED]",
      "created_at": "2025-11-10T13:00:00Z",
      "updated_at": "2025-11-10T13:00:00Z"
    },
    {
      "id": 125,
      "user_id": 456,
      "name": "Warn on Profanity",
      "is_enabled": false,
      "priority": 50,
      "scope": "response",
      "type": "substring",
      "pattern": "inappropriate",
      "action": "warn",
      "replacement": null,
      "created_at": "2025-11-10T14:00:00Z",
      "updated_at": "2025-11-10T14:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	integer	Unique rule identifier
user_id	integer	Owner user ID
name	string	Rule name
is_enabled	boolean	Whether rule is active
priority	integer	Rule priority (-1000 to 1000)
scope	string	prompt or response
type	string	substring or regex
pattern	string	Pattern to match
action	string	block, mask, or warn
replacement	string|null	Replacement text (only for mask action)
created_at	string	ISO timestamp of creation
updated_at	string	ISO timestamp of last update

Rule Ordering

Rules are returned in the order they will be evaluated during request processing:

1. By Priority (DESC) - Highest priority first
2. By ID (ASC) - Older rules first when priorities are equal

Example order:

Priority 100 (Block Credit Cards) → Evaluated first
Priority 80  (Mask Emails)       → Evaluated second
Priority 50  (Warn Profanity)    → Evaluated third

Filtering and Analysis

Filter by Scope

TypeScript

const response = await client.firewallRules.list();

// Get only prompt rules
const promptRules = response.data.filter(r => r.scope === 'prompt');

// Get only response rules
const responseRules = response.data.filter(r => r.scope === 'response');

console.log(`Prompt rules: ${promptRules.length}`);
console.log(`Response rules: ${responseRules.length}`);

Python

response = client.firewall_rules.list()

# Get only prompt rules
prompt_rules = [r for r in response.data if r.scope == "prompt"]

# Get only response rules
response_rules = [r for r in response.data if r.scope == "response"]

print(f"Prompt rules: {len(prompt_rules)}")
print(f"Response rules: {len(response_rules)}")

Filter by Action

TypeScript

const response = await client.firewallRules.list();

// Group by action
const blockRules = response.data.filter(r => r.action === 'block');
const maskRules = response.data.filter(r => r.action === 'mask');
const warnRules = response.data.filter(r => r.action === 'warn');

console.log(`Block rules: ${blockRules.length}`);
console.log(`Mask rules: ${maskRules.length}`);
console.log(`Warn rules: ${warnRules.length}`);

Python

response = client.firewall_rules.list()

# Group by action
block_rules = [r for r in response.data if r.action == "block"]
mask_rules = [r for r in response.data if r.action == "mask"]
warn_rules = [r for r in response.data if r.action == "warn"]

print(f"Block rules: {len(block_rules)}")
print(f"Mask rules: {len(mask_rules)}")
print(f"Warn rules: {len(warn_rules)}")

Find Active Rules

TypeScript

const response = await client.firewallRules.list();

// Get only enabled rules
const activeRules = response.data.filter(rule => rule.is_enabled);

console.log(`${activeRules.length} active rules out of ${response.data.length} total`);

// List active block rules (most critical)
const activeBlockRules = activeRules.filter(r => r.action === 'block');
activeBlockRules.forEach(rule => {
  console.log(`⚠️  ${rule.name} - blocks "${rule.pattern}"`);
});

Python

response = client.firewall_rules.list()

# Get only enabled rules
active_rules = [rule for rule in response.data if rule.is_enabled]

print(f"{len(active_rules)} active rules out of {len(response.data)} total")

# List active block rules (most critical)
active_block_rules = [r for r in active_rules if r.action == "block"]
for rule in active_block_rules:
    print(f"⚠️  {rule.name} - blocks \"{rule.pattern}\"")

Audit Rule Configuration

TypeScript

const response = await client.firewallRules.list();

// Find rules with no replacement text for mask action
const maskRulesWithoutReplacement = response.data.filter(
  r => r.action === 'mask' && !r.replacement
);

if (maskRulesWithoutReplacement.length > 0) {
  console.log('Rules using default [redacted] replacement:');
  maskRulesWithoutReplacement.forEach(r => console.log(`  - ${r.name}`));
}

// Find regex rules (more complex)
const regexRules = response.data.filter(r => r.type === 'regex');
console.log(`${regexRules.length} regex rules (may need testing)`);

Python

response = client.firewall_rules.list()

# Find rules with no replacement text for mask action
mask_rules_without_replacement = [
    r for r in response.data
    if r.action == "mask" and not r.replacement
]

if mask_rules_without_replacement:
    print("Rules using default [redacted] replacement:")
    for r in mask_rules_without_replacement:
        print(f"  - {r.name}")

# Find regex rules (more complex)
regex_rules = [r for r in response.data if r.type == "regex"]
print(f"{len(regex_rules)} regex rules (may need testing)")

Empty Response

If no rules exist, the response is an empty array:

{
  "data": []
}

Use Cases

Security Audit

Generate a security report of all firewall protections:

TypeScript

const rules = await client.firewallRules.list();

console.log('=== Firewall Security Audit ===\n');

console.log('🚫 BLOCKED PATTERNS:');
rules.data
  .filter(r => r.action === 'block' && r.is_enabled)
  .forEach(r => console.log(`  ${r.name}: ${r.pattern}`));

console.log('\n🎭 MASKED PATTERNS:');
rules.data
  .filter(r => r.action === 'mask' && r.is_enabled)
  .forEach(r => console.log(`  ${r.name}: ${r.pattern} → ${r.replacement}`));

console.log('\n⚠️  WARNING PATTERNS:');
rules.data
  .filter(r => r.action === 'warn' && r.is_enabled)
  .forEach(r => console.log(`  ${r.name}: ${r.pattern}`));

Python

rules = client.firewall_rules.list()

print("=== Firewall Security Audit ===\n")

print("🚫 BLOCKED PATTERNS:")
for r in [r for r in rules.data if r.action == "block" and r.is_enabled]:
    print(f"  {r.name}: {r.pattern}")

print("\n🎭 MASKED PATTERNS:")
for r in [r for r in rules.data if r.action == "mask" and r.is_enabled]:
    print(f"  {r.name}: {r.pattern} → {r.replacement}")

print("\n⚠️  WARNING PATTERNS:")
for r in [r for r in rules.data if r.action == "warn" and r.is_enabled]:
    print(f"  {r.name}: {r.pattern}")

Export Rules for Backup

TypeScript

import fs from 'fs';

const rules = await client.firewallRules.list();

// Export to JSON
const backup = {
  exported_at: new Date().toISOString(),
  rules: rules.data.map(r => ({
    name: r.name,
    priority: r.priority,
    is_enabled: r.is_enabled,
    scope: r.scope,
    type: r.type,
    pattern: r.pattern,
    action: r.action,
    replacement: r.replacement
  }))
};

fs.writeFileSync('firewall-backup.json', JSON.stringify(backup, null, 2));
console.log(`Exported ${backup.rules.length} rules`);

Python

import json
from datetime import datetime

rules = client.firewall_rules.list()

# Export to JSON
backup = {
    "exported_at": datetime.now().isoformat(),
    "rules": [
        {
            "name": r.name,
            "priority": r.priority,
            "is_enabled": r.is_enabled,
            "scope": r.scope,
            "type": r.type,
            "pattern": r.pattern,
            "action": r.action,
            "replacement": r.replacement
        }
        for r in rules.data
    ]
}

with open("firewall-backup.json", "w") as f:
    json.dump(backup, f, indent=2)

print(f"Exported {len(backup['rules'])} rules")

Next Steps

• Get Firewall Rule
• Create Firewall Rule
• Update Firewall Rule
• Delete Firewall Rule