Firewall API Overview

Overview

The Firewall API allows you to create content filtering rules that block, mask, or warn about sensitive content in requests and responses. Firewall rules help protect your applications by preventing sensitive data from being processed or returned.

Paid Plans Only

Firewall rules are only available on paid plans. Free plan users can view rules but cannot create, update, or delete them.

What are Firewall Rules?

Firewall rules let you define patterns that, when matched, trigger specific actions:

• Block - Reject the entire request/response (returns 422 error)
• Mask - Replace matched content with a replacement string
• Warn - Allow the request but add a warning to the response

Rule Evaluation

Rules are evaluated in priority order (highest first):

1. Rules with higher priority values execute first
2. Rules apply to either prompts (input) or responses (output)
3. Only enabled rules are evaluated (is_enabled: true)
4. Firewall rules are evaluated after routing rules in the pipeline

Base Endpoint

https://api.tokenrouter.io/v1/firewall-rules

Authentication

All Firewall API endpoints require authentication using your TokenRouter API key:

Authorization: Bearer tr_your_api_key

Common Operations

Operation	Method	Endpoint
List all rules	GET	/v1/firewall-rules
Get single rule	GET	/v1/firewall-rules/{id}
Create rule	POST	/v1/firewall-rules
Update rule	PATCH	/v1/firewall-rules/{id}
Delete rule	DELETE	/v1/firewall-rules/{id}

Rule Structure

Core Fields

{
  "name": "Block Credit Cards",
  "priority": 100,
  "is_enabled": true,
  "scope": "prompt",
  "type": "regex",
  "pattern": "\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}",
  "action": "block",
  "replacement": null
}

Scope

• prompt - Apply rule to user input before sending to LLM
• response - Apply rule to LLM output before returning to user

Type

• substring - Case-insensitive substring matching
• regex - Regular expression pattern matching (PCRE-compatible)

Action

• block - Reject request/response with 422 error
• mask - Replace matched content with replacement string (default: [redacted])
• warn - Add warning to response metadata but allow request

Quick Start Examples

Block Sensitive Keywords

TypeScript

import Tokenrouter from 'tokenrouter';

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

const rule = await client.firewallRules.create({
  name: 'Block Sensitive Keywords',
  priority: 100,
  is_enabled: true,
  scope: 'prompt',
  type: 'regex',
  pattern: '(password|ssn|credit.card)',
  action: 'block'
});

Python

from tokenrouter import Tokenrouter

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

rule = client.firewall_rules.create(
    name="Block Sensitive Keywords",
    priority=100,
    is_enabled=True,
    scope="prompt",
    type="regex",
    pattern=r"(password|ssn|credit\.card)",
    action="block"
)

cURL

curl https://api.tokenrouter.io/v1/firewall-rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_..." \
  -d '{
    "name": "Block Sensitive Keywords",
    "priority": 100,
    "is_enabled": true,
    "scope": "prompt",
    "type": "regex",
    "pattern": "(password|ssn|credit\\.card)",
    "action": "block"
  }'

Mask Email Addresses

TypeScript

const rule = await client.firewallRules.create({
  name: 'Mask Email Addresses',
  priority: 50,
  is_enabled: true,
  scope: 'response',
  type: 'regex',
  pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}',
  action: 'mask',
  replacement: '[EMAIL_REDACTED]'
});

Python

rule = client.firewall_rules.create(
    name="Mask Email Addresses",
    priority=50,
    is_enabled=True,
    scope="response",
    type="regex",
    pattern=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}",
    action="mask",
    replacement="[EMAIL_REDACTED]"
)

cURL

curl https://api.tokenrouter.io/v1/firewall-rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_..." \
  -d '{
    "name": "Mask Email Addresses",
    "priority": 50,
    "is_enabled": true,
    "scope": "response",
    "type": "regex",
    "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
    "action": "mask",
    "replacement": "[EMAIL_REDACTED]"
  }'

Warn on Profanity

TypeScript

const rule = await client.firewallRules.create({
  name: 'Warn on Profanity',
  priority: 30,
  is_enabled: true,
  scope: 'response',
  type: 'substring',
  pattern: 'badword',
  action: 'warn'
});

Python

rule = client.firewall_rules.create(
    name="Warn on Profanity",
    priority=30,
    is_enabled=True,
    scope="response",
    type="substring",
    pattern="badword",
    action="warn"
)

cURL

curl https://api.tokenrouter.io/v1/firewall-rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_..." \
  -d '{
    "name": "Warn on Profanity",
    "priority": 30,
    "is_enabled": true,
    "scope": "response",
    "type": "substring",
    "pattern": "badword",
    "action": "warn"
  }'

How Rules Are Applied

When a firewall rule matches:

Block Action

{
  "error": {
    "message": "Request blocked by firewall rule \"Block Sensitive Keywords\"",
    "type": "routing_error",
    "http_status": 422,
    "meta": {
      "rule_id": 123
    }
  }
}

Mask Action

Input: "My email is john@example.com" Output: "My email is [EMAIL_REDACTED]"

Warn Action

{
  "metadata": {
    "warnings": ["Profanity detected in response"],
    "applied_rules": ["Warn on Profanity"]
  }
}

Response Metadata

When firewall rules are applied, the response includes metadata:

{
  "metadata": {
    "applied_rules": ["Mask Email Addresses"],
    "warnings": []
  }
}

Common Use Cases

Use Case	Scope	Type	Action
Block credit card numbers	prompt	regex	block
Mask SSNs in responses	response	regex	mask
Block API keys	prompt	regex	block
Redact names	response	substring	mask
Warn about profanity	response	substring	warn
Block SQL injection	prompt	regex	block

Next Steps

• Create a Firewall Rule
• List Firewall Rules
• Update Firewall Rules
• Delete Firewall Rules