Agent Setup Guide

{
  "data": null,
  "error": {
    "code":    "AGENT_PAUSED",
    "message": "Agent \"Refund Agent v2\" is paused. Resume the agent in the dashboard before submitting intents."
  }
}

curl -X POST https://silentauth.ai/api/intents \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action":      "issue_refund",
    "source_type": "ai_agent",
    "source":      "refund-agent-v1",
    "risk_tier":   "high",
    "parameters":  {
      "customer_id": "cust_4821",
      "amount": 50.00
    }
  }'

{
  "id":       "a3f2c1b0-4e52-4d1a-9b0f-12c34d56e789",
  "decision": "require_approval",
  "data": {
    "id":          "a3f2c1b0-...",
    "status":      "pending",
    "action":      "issue_refund",
    "risk_tier":   "high",
    "source":      "refund-agent-v1",
    "parameters":  { "customer_id": "cust_4821", "amount": 50.00 },
    "created_at":  "2026-03-16T12:00:00.000Z"
  }
}

import requests, time

def wait_for_approval(intent_id, secret_key, timeout_seconds=600):
    """Block until the intent is approved or denied."""
    headers = {"Authorization": f"Bearer {secret_key}"}
    base    = "https://silentauth.ai"
    deadline = time.time() + timeout_seconds

    while time.time() < deadline:
        time.sleep(5)

        # Check approved intents
        approved = requests.get(
            f"{base}/api/intents?status=approved",
            headers=headers,
        ).json()
        for intent in approved.get("data", []):
            if intent["id"] == intent_id:
                return intent["permit_token"]   # ✓ approved

        # Check denied intents
        denied = requests.get(
            f"{base}/api/intents?status=denied",
            headers=headers,
        ).json()
        for intent in denied.get("data", []):
            if intent["id"] == intent_id:
                raise PermissionError(f"Intent denied: {intent_id}")

    raise TimeoutError(f"Timed out after {timeout_seconds}s")

def issue_refund(customer_id: str, amount: float):
    # Step 1: Declare intent
    resp = requests.post(
        "https://silentauth.ai/api/intents",
        headers={"Authorization": f"Bearer {SECRET_KEY}"},
        json={
            "action":      "issue_refund",
            "source_type": "ai_agent",
            "risk_tier":   "high",
            "parameters":  {"customer_id": customer_id, "amount": amount},
        },
    )
    result = resp.json()

    if result["decision"] == "auto_deny":
        raise PermissionError("Blocked by policy")

    if result["decision"] == "auto_approve":
        permit = result["data"]["permit_token"]
    else:
        # Blocks here until a human approves (or timeout)
        permit = wait_for_approval(result["id"], SECRET_KEY)

    # Step 4: Execute — pass permit to your backend
    payment_service.refund(
        customer_id=customer_id,
        amount=amount,
        permit_token=permit,   # Backend verifies this
    )

{
  "event":        "intent.approved",
  "intent_id":    "a3f2c1b0-...",
  "project_id":   "proj_...",
  "action":       "issue_refund",
  "source":       "refund-agent-v1",
  "source_type":  "ai_agent",
  "risk_tier":    "high",
  "status":       "approved",
  "parameters":   { "customer_id": "cust_4821", "amount": 50.00 },
  "permit_token": "eyJhbGciOiJIUzI1NiJ9...",
  "approved_by":  "admin@example.com",
  "timestamp":    "2026-03-16T12:34:56.000Z"
}

import hmac, hashlib
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_signing_secret"

@app.route("/webhooks/silentauth", methods=["POST"])
def handle_webhook():
    body      = request.get_data()
    sig       = request.headers.get("X-SilentAuth-Signature", "")
    expected  = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(),
        body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, sig):
        abort(401)   # Invalid signature — reject

    payload = request.json
    if payload["event"] == "intent.approved":
        permit_token = payload["permit_token"]
        intent_id    = payload["intent_id"]
        # Resume the waiting agent thread here
        resolve_pending_intent(intent_id, permit_token)

    return "", 200

import requests, time, os

SECRET_KEY = os.environ["SILENTAUTH_SECRET_KEY"]
BASE_URL   = "https://silentauth.ai"

def require_approval(action, risk_tier="medium", source="my-agent", parameters=None):
    """Declare an intent and block until a human approves or policy resolves it."""
    headers = {
        "Authorization": f"Bearer {SECRET_KEY}",
        "Content-Type":  "application/json",
    }
    resp = requests.post(
        f"{BASE_URL}/api/intents",
        headers=headers,
        json={
            "action":      action,
            "source_type": "ai_agent",
            "source":      source,
            "risk_tier":   risk_tier,
            "parameters":  parameters or {},
        },
    )
    resp.raise_for_status()
    result = resp.json()

    intent_id = result["id"]
    decision  = result.get("decision", "require_approval")

    if decision == "auto_approve":
        return result["data"]["permit_token"]

    if decision == "auto_deny":
        raise PermissionError(f"Intent {intent_id} was auto-denied by policy")

    # Poll until human resolves (timeout: 10 minutes)
    deadline = time.time() + 600
    while time.time() < deadline:
        time.sleep(5)

        approved = requests.get(
            f"{BASE_URL}/api/intents?status=approved",
            headers=headers,
        ).json()
        for intent in approved.get("data", []):
            if intent["id"] == intent_id:
                return intent["permit_token"]

        denied = requests.get(
            f"{BASE_URL}/api/intents?status=denied",
            headers=headers,
        ).json()
        for intent in denied.get("data", []):
            if intent["id"] == intent_id:
                raise PermissionError(f"Intent {intent_id} was denied")

    raise TimeoutError(f"Intent {intent_id} timed out after 10 minutes")


# --- Usage examples ---

def issue_refund(customer_id: str, amount: float):
    permit = require_approval(
        action="issue_refund",
        risk_tier="high",
        parameters={"customer_id": customer_id, "amount": amount},
    )
    print(f"Permit: {permit[:40]}…")
    # ← proceed with actual refund

def delete_account(user_id: str):
    permit = require_approval(
        action="delete_account",
        risk_tier="critical",
        parameters={"user_id": user_id},
    )
    print(f"Permit: {permit[:40]}…")
    # ← proceed with account deletion

def read_profile(user_id: str):
    # Low-risk — likely auto-approved by policy, no human needed
    permit = require_approval(
        action="read_profile",
        risk_tier="low",
        parameters={"user_id": user_id},
    )
    # ← proceed immediately