Security

Built-in safeguards to protect your agents, users, and outbound communications.

API Keys

Two types: Master Keys (full admin access) and Agent Keys (scoped to a single mailbox).

Dual-Layer Content Scanning

Scans with both deterministic regex heuristics and AI classification.

API Key Types

Type	Prefix	Permissions	Best Practice
Master Key	`mk_`	Full access. Create agents, manage billing, view logs.	Store in server-only environment variables and rotate on schedule.
Agent Key	`ak_`	Scoped access. Send/receive for one specific agent.	Issue least-privilege keys per service and revoke unused keys.

Reaching master authority

A MASTER_KEY_REQUIRED (403) means the operation needs org-admin authority and the credential you used does not carry it — around a hundred endpoints sit behind that gate, including agent creation, key management, billing, and the event stream. Which route out is open depends on how you authenticated:

Route	How	Notes
Master key	Copy your `mk_` key from the console and send it as the bearer token.	Server-side only. Never ship it to a browser, and never hand it to an agent.
Console session	Sign in as an organization owner or admin.	Vault reveals additionally require a recent first-factor check — see Vault reveal policy.
OAuth	Request the `admin:full` scope during `/oauth/authorize`.	Anima Connect applications.
CLI	Just run the command — it steps up on its own.	Prompts for your OS login password. Enrolment is macOS-only and needs an interactive terminal once — see below.

Admin access from the CLI

There is no command to run first. A command that needs admin rights — anima agent create, key rotation, anima tail — asks for it itself, and your OS prompts for your login password. The first time on a given machine, the CLI emails a code to the organization owner and enrols that machine inline, at the moment you need it. Enrolment stores a grant in the OS keychain behind a human-presence gate, so later commands need only the password prompt rather than another email. Admin access lasts for the single command that asked for it and is never written to disk, so each admin command prompts.

An agent driving the CLI holds your API key and can run every command, but it cannot answer a system password dialog. That is the boundary, and it is deliberate. The gate is local: it governs release of the grant on this machine, and the server cannot verify that a human was present — so treat it as narrowing who can obtain admin authority here, not as a guarantee about what that authority can do once obtained.

Enrolment is macOS-only. On other platforms the CLI refuses to store a grant rather than pretend it is protected, so every step-up uses the emailed code. Enrolment also needs an interactive terminal once, because the code has to be typed back in — a CI job or an agent driving the CLI fails with that explanation instead of blocking on a prompt nothing will answer.

Content Scanning Overview (Regex + AI)

Regex Layer: Fast checks for known injection markers, secret patterns, and risky payload signatures.
AI Layer: GPT-4o-mini classification into SAFE, SUSPICIOUS, or BLOCKED.
Fallback Safety: If AI credentials are missing, scanning gracefully continues in regex-only mode.

Note: Use low, medium (default), or high sensitivity depending on risk tolerance and expected message variability.

Content Policy Configuration

The policy engine applies layered rules to outbound content and can combine deterministic and model-based checks.

Regex rules: Match known dangerous patterns.
AI rules: Enforce decisions based on model classification.
Domain rules: Whitelist or blacklist domains in message content.
Keyword rules: Detect finance, attachment, and social engineering signals.

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" }
    ]
  }
];

Agent Capability Policies

Separate from content scanning: each agent carries an optional capability policy — hard limits an org admin sets on what the agent may do, regardless of message content. Read it with GET /v1/agents/{agentId}/policy (any key in the org). Write it with PUT /v1/agents/{agentId}/policy (master key only):

curl -X PUT https://api.useanima.sh/v1/agents/agt_.../policy \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "email": {
        "allowedRecipientDomains": ["example.com"],
        "blockedRecipientDomains": [],
        "maxPerHour": 20
      },
      "vault": { "readOnly": true, "blocked": false },
      "phone": { "allowedCountries": ["US", "DE"], "maxSmsPerHour": 10, "blocked": false }
    }
  }'

Field	Type	Meaning
`email.allowedRecipientDomains`	`string[]`	If non-empty, the agent may only send to these domains. Empty = no restriction.
`email.blockedRecipientDomains`	`string[]`	The agent may never send to these domains.
`email.maxPerHour`	`number`	Per-agent override of the emails-per-hour rate limit.
`vault.readOnly`	`boolean`	Agent can read vault items but not create, update, or delete them.
`vault.blocked`	`boolean`	Disable vault access for this agent entirely.
`phone.allowedCountries`	`string[]`	ISO 3166-1 alpha-2 codes. If non-empty, the agent may only call/text these countries.
`phone.maxSmsPerHour`	`number`	Per-agent override of the SMS-per-hour rate limit.
`phone.blocked`	`boolean`	Disable phone/SMS for this agent entirely.

Every section is optional — omit one to leave that channel unrestricted. Validation is strict: unknown fields are rejected with a 400 rather than silently ignored, so typos can’t create a policy that looks stricter than it is. An email send that violates the policy is refused and logged as a security event, so blocked attempts show up in the audit trail.

Note: Email constraints are enforced on every send today. Vault and phone constraints are validated and stored, but not yet enforced at request time.

Rate Limiting for AI Scanning

AI scanning is rate limited to 100 req/min, uses an LRU cache with 1000 entries and a 5min TTL, and falls back to regex scanning when needed.

Attachment Scanning

Email attachments are scanned both when an agent receives them and before an agent sends them, so malicious files are caught in either direction.

Magic-byte detection: the actual leading bytes are inspected, not the declared type or the file extension (both are trivially spoofed). An executable or script disguised as invoice.pdf is unmasked and blocked.
Content scanning: text attachments run through the same content scanner as message bodies, catching leaked credentials, PII, and risky file types.
Verdict: each attachment gets a scanStatus of CLEAN, FLAGGED, or BLOCKED, surfaced in the message’s attachment metadata so an agent can decide before fetching the bytes.

A BLOCKED attachment cannot be downloaded — the download endpoint returns 403. Download URLs are short-lived (15 minutes) and scoped to the requesting agent.

Webhook Security (HMAC Verification)

Webhook payloads are protected with HMAC verification and freshness checks to prevent tampering and replay attacks.

Use a dedicated webhook secret.
Verify the HMAC signature on every request.
Compare signatures using constant-time comparison.
Reject requests that fail timestamp freshness checks.

Warning: If content is blocked by policy, the API returns a denial response with a reason code so you can audit and tune policy behavior safely.

Operational Best Practices

Rotate keys on a regular schedule.
Store master keys only in server-side environments.
Use least-privilege agent keys per service.
Review blocked events and adjust policies carefully.

Getting Started

Framework Toolkits

Platform

Agent Identity & A2A

Security

Compliance

Protocols

SDK Reference

Resources

Legal

Blog

Security

Security

API Keys

Dual-Layer Content Scanning

API Key Types

Reaching master authority

Admin access from the CLI

Content Scanning Overview (Regex + AI)

Content Policy Configuration

Agent Capability Policies

Rate Limiting for AI Scanning

Attachment Scanning

Webhook Security (HMAC Verification)

Operational Best Practices

​Security

​API Keys

​Dual-Layer Content Scanning

​API Key Types

​Reaching master authority

​Admin access from the CLI

​Content Scanning Overview (Regex + AI)

​Content Policy Configuration

​Agent Capability Policies

​Rate Limiting for AI Scanning

​Attachment Scanning

​Webhook Security (HMAC Verification)

​Operational Best Practices

Security

API Keys

Dual-Layer Content Scanning

API Key Types

Reaching master authority

Admin access from the CLI

Content Scanning Overview (Regex + AI)

Content Policy Configuration

Agent Capability Policies

Rate Limiting for AI Scanning

Attachment Scanning

Webhook Security (HMAC Verification)

Operational Best Practices