Integrations

AIdenID provides multiple integration patterns to fit your clearance architecture. Start with an edge or origin verifier for agent traffic, then add supporting APIs, webhooks, MCP, and evidence streams where your workflow needs them.

Verifier integration

The primary integration is the clearance gate itself: mount AIdenID at the edge or origin, register route policy, and receive a six-outcome decision before sensitive handlers execute. Teams usually start in observe mode, run shadow comparisons, then enforce route by route.

• Actor classes: verified_agent, signed_agent, likely_human, suspicious_automation, unknown
• Outcomes: allow, throttle, queue, sandbox, deny, price_required
• Modes: observe, shadow, enforce

REST control plane

The AIdenID REST API provides programmatic access to supporting control-plane features: targets, identities, webhooks, auth-flow test evidence, billing, exports, and quotas. Use standard HTTP requests with JSON payloads and bearer token authentication.

• Base URL: https://api.aidenid.com
• Format: JSON request and response bodies
• Auth: Bearer token via Authorization header
• Idempotency: Required for all mutations via Idempotency-Key header

See the API Reference for complete endpoint documentation.

Webhooks

Register HTTPS endpoints to receive real-time event notifications. Webhooks eliminate the need for polling and enable event-driven architectures. All payloads are signed with HMAC-SHA256.

Webhook integration guide

MCP Server

The AIdenID MCP (Model Context Protocol) server allows LLMs to use AIdenID tools directly through tool calling. MCP is a support surface for issuer, identity, and demo workflows; it is not on the request hot path for clearance decisions.

MCP server setup guide

Server-Sent Events (SSE)

Connect to a real-time event stream for live updates. SSE powers the decision dashboard and supporting identity/inbox surfaces. Events include decisions, policy updates, revocations, identity changes, extraction completions, and inbound email arrivals.

Realtime SSE documentation

Consumer web inbox

Human consumers interact with the supporting inbox product through a web UI that uses SSE for real-time updates. No API integration is needed — the web UI handles identity creation, redacted extraction display, and email forwarding automatically. See Consumer API.

Integration patterns

Clearance decision pattern

Mount a verifier, configure route policy, and evaluate each request before origin handlers receive it.

# Pseudocode
decision = aidenid.evaluate_request(request, route="/checkout")
if decision.action == "allow":
    forward_to_origin(request, decision_context=decision)
elif decision.action == "price_required":
    return payment_required(decision)
elif decision.action in {"throttle", "queue", "sandbox"}:
    return controlled_fallback(decision)
else:
    return deny(decision)

Polling pattern

The simplest integration. Create an identity, use the email in a flow, then poll the extraction endpoint until a result is available.

# Pseudocode
identity = create_identity(label="signup")
use_email_in_signup_flow(identity.email)

MAX_ATTEMPTS = 30  # ~60s total wait
for attempt in range(MAX_ATTEMPTS):
    extraction = get_latest_extraction(identity.id)
    if extraction:
        send_secret_to_secure_runtime(extraction)
        break
    sleep(2)
else:
    raise TimeoutError("Extraction not received within timeout")

squash_identity(identity.id)

Webhook-driven pattern

Register a webhook for extraction.completed events. When an extraction is ready, your server receives a push notification with the extracted value. No polling required.

# 1. Register webhook (one-time setup)
POST /v1/webhooks
{
  "url": "https://your-server.com/hooks/aidenid",
  "events": ["extraction.completed"]
}

# 2. Create identity and use it
POST /v1/identities
use_email_in_signup_flow(identity.email)

# 3. Your webhook handler receives the extraction
# POST https://your-server.com/hooks/aidenid
# { "type": "extraction.completed", "data": { ... } }

MCP tool-calling pattern

Configure the AIdenID MCP server in your LLM environment. The LLM can then directly call AIdenID tools as part of its reasoning loop.

// LLM tool call
{
  "tool": "create_identity",
  "arguments": { "label": "signup-agent", "ttl_hours": 1 }
}

// LLM receives identity with email address
// LLM uses email in signup flow
// LLM calls get_latest_extraction to retrieve OTP

Language support

The REST API works with any language that can make HTTP requests. Here are some common options:

Next steps

• Set up webhooks
• Configure MCP server
• Follow the quickstart