Skip to main content
Anima gives you layered controls to protect your agents, your users, and the data flowing through your integration — from API key scoping to AI-powered content scanning.

​
API keys

Anima issues two types of API keys. Use the right key for each context.
TypePrefixWhat it can doBest practice
Master Keymk_Full access: create agents, manage billing, view logsStore in server-only environment variables; rotate on a schedule
Agent Keyak_Scoped access: send and receive for one specific agentIssue one key per service; revoke unused keys immediately
Never expose a Master Key in client-side code, mobile apps, or version control. A compromised Master Key grants full account access.

​
Content scanning

Every outbound message passes through a dual-layer scanner before delivery.
  • Regex layer — Fast, deterministic checks for known injection markers, secret patterns, and risky payload signatures.
  • AI layer — GPT-4o-mini classifies content as SAFE, SUSPICIOUS, or BLOCKED.
  • Fallback behavior — If AI credentials are unavailable, scanning continues in regex-only mode so your agents keep running.

​
Sensitivity levels

Adjust sensitivity to match your risk tolerance and message variability.
LevelWhen to use
lowHigh-volume, well-structured automated messages with low risk of injection
mediumDefault. Balanced protection for most integrations
highCustomer-facing or regulated contexts where false negatives are costly
When content is blocked by policy, the API returns a denial response with a reason code. Use these codes to audit and tune your policies over time.

​
Content policies

The policy engine applies layered rules to outbound content. Rules are evaluated in priority order and can combine deterministic and model-based checks.
Rule typeWhat it does
RegexMatches known dangerous patterns (e.g., prompt injection phrases)
AIEnforces decisions based on model classification verdict
DomainWhitelists or blacklists domains appearing in message content
KeywordDetects finance, attachment, and social engineering signals
Define policies in your integration configuration: 
const policies = [
  {
    id: "block-injection",
    name: "Block Injection",
    action: "block",
    priority: 100,
    rules: [
      { type: "regex", value: "ignore\\s+previous\\s+instructions", description: "Prompt injection" },
      { type: "ai", value: ["BLOCKED"], description: "AI high-risk verdict" }
    ]
  }
];

​
AI scanning rate limits

AI scanning is rate-limited to 100 requests per minute. Results are cached using an LRU cache (1,000 entries, 5-minute TTL) to reduce redundant scans on repeated content. When the rate limit is reached, the scanner falls back to regex-only mode automatically.

​
Webhook security

Anima signs every webhook payload with HMAC so you can verify that requests come from Anima and haven’t been tampered with. Follow these steps to verify incoming webhooks securely:
1

Use a dedicated webhook secret

Generate a unique secret for each webhook endpoint. Do not reuse secrets across endpoints or environments.
2

Verify the HMAC signature

Compare the X-Anima-Signature header against an HMAC-SHA256 digest of the raw request body using your secret.
3

Use constant-time comparison

Compare signatures with a constant-time function to prevent timing attacks. Never use a plain equality check.
4

Check timestamp freshness

Reject requests where the X-Anima-Timestamp header is older than your acceptable window (typically 5 minutes) to prevent replay attacks.

​
Operational best practices

Set a calendar reminder to rotate Master Keys at least quarterly. Agent Keys can be rotated more frequently if they are short-lived or service-specific. Anima supports issuing a new key before revoking the old one to avoid downtime.
Issue one Agent Key per downstream service. If a service is compromised, you can revoke just its key without affecting other integrations. Never use a Master Key where an Agent Key will do.
Check your blocked content events in the audit log on a regular cadence. Unexpected blocks may indicate a misconfigured policy or an active attack. Tune sensitivity levels and rules based on what you find.
Master Keys and webhook secrets must only exist in server-side code or a secrets manager. Never bundle them into client applications, browser code, or commit them to version control.