Integration Guide

This guide is for platform teams integrating VeriSwarm as a trust and moderation layer. It covers API keys, decision checks, event ingestion, reports, and billing.

Your workspace

A VeriSwarm workspace is an account with API and billing capabilities enabled. With it, you can:

  • Manage API keys
  • View plan and usage details
  • Configure outbound webhooks
  • Access provider analytics

Enable provider mode from your account console.

Typical workflow

  1. Create a VeriSwarm account and enable provider mode
  2. Generate an API key from the account console
  3. Register or link your agents
  4. Send events and reports as agents operate
  5. Call decision checks before sensitive actions

API keys

Create and revoke API keys from the account console. Your platform systems should authenticate with API keys, not user login tokens. Keys can be rotated independently without affecting your account.

Best practices:

  • Store keys in a secret manager
  • Label keys by environment or service
  • Revoke unused keys promptly

Decision checks

Decision checks are the core runtime integration — call them before any action that needs a trust gate.

Endpoint: POST /v1/decisions/check

Use before actions like:

  • Posting public content
  • Joining shared channels
  • Invoking sensitive tools
  • Creating agent-visible content

The response includes a decision, reason_code, and policy_tier. Handle decisions as follows:

  • allow — proceed normally
  • review — route to moderation or secondary checks
  • deny — block or sandbox the action

Event ingestion

Events are the behavioral input that drives scoring.

Endpoint: POST /v1/events

Send events for meaningful agent activity:

  • Content posted
  • Tasks completed
  • Policy incidents observed
  • Key rotations or identity refreshes
  • External moderation signals

When async ingestion is enabled, scoring completes shortly after the event is accepted rather than inline.

Provider reports

Send structured trust and abuse signals from your own moderation systems via the reports API. Supports both single and batch submission.

Use reports for:

  • Abuse complaints
  • Scam or deception findings
  • Spam bursts
  • External account linkage evidence
  • Attestation refreshes from your own systems

Agent linking

If your platform has its own agent IDs, link them to VeriSwarm identities. This keeps your internal records and VeriSwarm in sync and prevents identity drift.

When registering an agent, store the returned VeriSwarm agent ID alongside your internal record.

Billing and plans

The account console shows your current plan, daily quota usage, remaining quota, subscription state, and payment methods.

Available plans: Free, Pro, Team, and Enterprise.

Analytics and webhooks

VeriSwarm provides:

  • Usage analytics — track API calls and quota consumption
  • Trust analytics — monitor trust posture by day or week
  • Webhook management — push decisions and changes back into your platform
  • Delivery history — audit webhook reliability

Integration pattern

At registration: Register each agent in VeriSwarm and store the returned agent ID.

During runtime: Send meaningful events, forward abuse or trust reports from your own systems, and call decision checks before sensitive actions.

During incident response: Inspect recent flags and scores, review timeline history, and decide whether to quarantine, challenge, or restore the agent.

Failure handling

When VeriSwarm is unavailable, apply a safe default posture:

  • Low-risk actions: treat as review
  • High-risk actions: treat as deny
  • Log every fallback for later audit

This matches VeriSwarm's safety bias -- unknown trust states default toward caution, not permissiveness.

Guard Proxy

Guard Proxy is a transparent MCP proxy that intercepts every tool call between your agents and their MCP servers. It applies policy checks, PII tokenization, prompt injection scanning, and audit logging -- with no agent-side code changes.

Cloud-hosted (recommended)

The fastest setup. Replace your agent's MCP server URL with the VeriSwarm proxy URL:

# Before
MCP_SERVER_URL=https://my-mcp-server.example.com

# After
MCP_SERVER_URL=https://proxy.veriswarm.ai/v1/guard/proxy/my-mcp-server

Or generate the config from the SDK:

Python:

config = client.guard_proxy_config(agent_id="agt_123", server="my-mcp-server")

Node:

const config = client.guardProxyConfig({ agentId: "agt_123", server: "my-mcp-server" });

Docker (on-prem)

For production deployments where traffic must stay in your network:

docker run -d \
  -e VERISWARM_API_KEY=vsk_... \
  -e UPSTREAM_MCP_URL=https://my-mcp-server.example.com \
  -p 8080:8080 \
  veriswarm/guard-proxy:latest

Point your agents at http://localhost:8080 (or your internal DNS).

Default protections

When Guard Proxy is active, the following are enabled by default:

  • PII tokenization -- sensitive data in requests and responses is replaced with typed tokens
  • Policy enforcement -- tool allowlists and blocklists are applied
  • Prompt injection scanning -- tool responses are checked for injection attempts
  • Audit logging -- every tool call is recorded

For full Guard documentation including PII rehydration, kill switch, and tool policies, see Guard.

Related guides