SOXAgent Documentation

Authorization: Bearer sk_live_your_key_here

x-api-key: sk_live_your_key_here

Authorization: Bearer sk_live_abc123...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

curl -X POST https://soxagent-api.fly.dev/v1/authorizations \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "action": { "type": "refund_approve", "amount": 100 }, "agent": { "agent_id": "my-agent" } }'

curl -X POST https://soxagent-api.fly.dev/v1/authorizations \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "action": {
      "type": "refund_approve",
      "amount": 150.00,
      "currency": "USD"
    },
    "agent": {
      "agent_id": "support-refund-agent"
    },
    "rationale_summary": "Customer refund for order #12345"
  }'

{
  "request_id": "req_abc123",
  "status": "success",
  "data": {
    "id": "aut_7f3k9m2x",
    "state": "approved",
    "decision": "approved",
    "decision_mode": "auto",
    "action_type": "refund_approve",
    "amount": 150.00,
    "currency": "USD",
    "agent_id": "support-refund-agent",
    "risk_tier": "low",
    "risk_score": 12,
    "reason_codes": [],
    "winning_policy": {
      "policy_id": "pol_default",
      "version": 1
    },
    "decision_token": "dt_a1b2c3d4...",
    "timeout_at": null,
    "created_at": "2026-03-18T12:00:00.000Z",
    "agent_governance": {
      "governance_status": "registered",
      "control_tier": "standard",
      "environment": "production",
      "business_owner": "Jane Smith",
      "action_in_scope": true
    }
  }
}

{
  "request_id": "req_def456",
  "status": "success",
  "data": {
    "id": "aut_9k4m2n8p",
    "state": "pending_human_approval",
    "decision": "escalated",
    "decision_mode": "policy",
    "action_type": "refund_approve",
    "amount": 5000.00,
    "currency": "USD",
    "agent_id": "support-refund-agent",
    "risk_tier": "medium",
    "risk_score": 45,
    "reason_codes": ["amount_exceeds_threshold"],
    "winning_policy": {
      "policy_id": "pol_default",
      "version": 1
    },
    "decision_token": null,
    "approval_routing": {
      "approver_role": "finance_manager",
      "timeout_minutes": 1440,
      "timeout_disposition": "deny"
    },
    "approval_task": {
      "approval_id": "apr_x1y2z3",
      "approver_role": "finance_manager",
      "sla_due_at": "2026-03-19T12:00:00.000Z"
    },
    "timeout_at": "2026-03-19T12:00:00.000Z",
    "created_at": "2026-03-18T12:00:00.000Z"
  }
}

{
  "request_id": "req_ghi789",
  "status": "error",
  "error": {
    "code": "POLICY_DENIED",
    "message": "Action denied by policy: prohibited action type"
  }
}

{
  "decision_token": "dt_a1b2c3d4...",
  "execution_result": {
    "status": "succeeded",
    "executed_at": "2026-03-18T12:05:00.000Z",
    "amount": 150.00,
    "currency": "USD",
    "external_transaction_id": "txn_stripe_abc123"
  }
}

{
  "request_id": "req_jkl012",
  "status": "success",
  "data": {
    "authorization_id": "aut_7f3k9m2x",
    "state": "execution_confirmed",
    "execution": {
      "status": "succeeded",
      "external_transaction_id": "txn_stripe_abc123",
      "executed_at": "2026-03-18T12:05:00.000Z"
    },
    "reconciliation": {
      "status": "matched",
      "authorized_amount": 150.00,
      "executed_amount": 150.00,
      "variance": 0
    }
  }
}

curl https://soxagent-api.fly.dev/v1/authorizations/aut_7f3k9m2x/evidence \
  -H "Authorization: Bearer sk_live_abc123..."

HMAC-SHA256(webhook_secret, "{timestamp}.{body}")

{
  "request_id": "req_abc123",
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}
  }
}

# Use sk_test_ keys during development, sk_live_ keys in production
curl -X POST https://soxagent-api.fly.dev/v1/authorizations \
  -H "Authorization: Bearer $SOXAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "action": {
      "type": "refund_approve",
      "amount": 150.00,
      "currency": "USD"
    },
    "agent": {
      "agent_id": "support-refund-agent"
    }
  }'

const SOXAGENT_API = "https://soxagent-api.fly.dev";
// Use SOXAGENT_TEST_KEY (sk_test_...) in dev, SOXAGENT_API_KEY (sk_live_...) in prod
const API_KEY = process.env.SOXAGENT_API_KEY;

async function authorize(actionType, amount, currency, agentId) {
  const res = await fetch(`${SOXAGENT_API}/v1/authorizations`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      action: { type: actionType, amount, currency },
      agent: { agent_id: agentId },
    }),
  });

  const json = await res.json();

  if (json.status === "success") {
    const { decision, decision_token } = json.data;
    console.log(`Decision: ${decision}`);
    if (decision === "approved") {
      // Proceed with the action, then report execution
      return { approved: true, token: decision_token };
    }
    return { approved: false, decision };
  }

  throw new Error(json.error?.message || `API error: ${res.status}`);
}

// Usage
const result = await authorize("refund_approve", 150, "USD", "support-refund-agent");

import os
import uuid
import requests

SOXAGENT_API = "https://soxagent-api.fly.dev"
# Use SOXAGENT_TEST_KEY (sk_test_...) in dev, SOXAGENT_API_KEY (sk_live_...) in prod
API_KEY = os.environ["SOXAGENT_API_KEY"]

def authorize(action_type: str, amount: float, currency: str, agent_id: str):
    resp = requests.post(
        f"{SOXAGENT_API}/v1/authorizations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
            "Idempotency-Key": str(uuid.uuid4()),
        },
        json={
            "action": {"type": action_type, "amount": amount, "currency": currency},
            "agent": {"agent_id": agent_id},
        },
    )
    resp.raise_for_status()
    data = resp.json()

    if data["status"] == "success":
        decision = data["data"]["decision"]
        token = data["data"].get("decision_token")
        print(f"Decision: {decision}")
        if decision == "approved":
            return {"approved": True, "token": token}
        return {"approved": False, "decision": decision}

    raise Exception(data.get("error", {}).get("message", f"API error: {resp.status_code}"))

# Usage
result = authorize("refund_approve", 150.00, "USD", "support-refund-agent")