Authorization Engine

Overview

The authorization engine processes every transaction request through a multi-stage pipeline that evaluates compliance, risk, and behavioral trust in real time. Decisions are returned in under 200ms at the 99th percentile.

The engine produces one of three decisions: APPROVE, DECLINE, or STEP_UP (requires additional verification). Each decision includes detailed metadata about which checks passed or failed, enabling full auditability.

The authorization pipeline

Every authorization request flows through these stages sequentially. If any stage produces a terminal decision, the pipeline short-circuits and returns immediately.

Request format

The POST /api/v1/authorize endpoint accepts the following fields:

Response format

The authorization response provides the decision along with all signals that contributed to it:

{
  "decision": "APPROVE",
  "authorization_id": "auth_7f3k9x2m",
  "agent_id": "agent_abc123",
  "amount": "42.99",
  "currency": "USD",
  "trust_score": 0.87,
  "risk_score": 0.12,
  "gates_fired": [],
  "cognitive_limit_multiplier": 1.0,
  "effective_limit": "500.00",
  "mandate_id": "mnd_xyz789",
  "recommendations": [],
  "timestamp": "2026-05-25T14:32:01.234Z"
}

Decisions

APPROVE

The transaction passed all checks. The agent is within mandate limits, risk is acceptable, and cognitive trust is sufficient. Process the payment.

DECLINE

The transaction was rejected. Check gates_fired for specific reasons and recommendations for suggested remediation. Common decline reasons: mandate exceeded, high risk score, critical CTS zone, or intent anomaly detected.

STEP_UP

The transaction requires additional verification before it can proceed. This occurs when the system detects moderate risk or ambiguity. Implement a step-up challenge (e.g., re-confirm with the human principal) and re-submit if confirmed.

Gates

Gates are named safety checks that can fire during authorization. When a gate fires, it appears in the gates_fired array and may influence the decision.

Code examples

Complete authorization flow with error handling:

from mandate_ai_sdk import MandateAI
from mandate_ai_sdk.models import AuthorizeRequest

client = MandateAI(api_key="mdt_test_abc123...")

# Submit authorization request
result = client.authorization.authorize(AuthorizeRequest(
    agent_id="agent_abc123",
    amount="149.99",
    currency="USD",
    merchant="Amazon Web Services",
    mcc="5734",
    intent_context={
        "task": "cloud_infrastructure_scaling",
        "reasoning": "Auto-scaling triggered by traffic spike",
        "confidence": 0.95,
    },
    session_id="sess_daily_ops_20260525",
))

# Handle the decision
if result.decision == "APPROVE":
    print("Transaction approved")
    process_payment(result.authorization_id)
elif result.decision == "STEP_UP":
    print(f"Step-up required. Gates: {result.gates_fired}")
    # Request human confirmation, then re-submit
elif result.decision == "DECLINE":
    print(f"Declined. Reasons: {result.gates_fired}")
    print(f"Recommendations: {result.recommendations}")

# Query authorization history
logs = client.authorization.logs(agent_id="agent_abc123", limit=10)
for log in logs:
    print(f"{log.timestamp} | {log.decision} | {log.amount} {log.currency}")

import { MandateAI } from "@mandate-ai/sdk";

const client = new MandateAI({ apiKey: "mdt_test_abc123..." });

// Submit authorization request
const result = await client.authorization.authorize({
  agent_id: "agent_abc123",
  amount: "149.99",
  currency: "USD",
  merchant: "Amazon Web Services",
  mcc: "5734",
  intent_context: {
    task: "cloud_infrastructure_scaling",
    reasoning: "Auto-scaling triggered by traffic spike",
    confidence: 0.95,
  },
  session_id: "sess_daily_ops_20260525",
});

// Handle the decision
if (result.decision === "APPROVE") {
  console.log("Transaction approved");
  processPayment(result.authorization_id);
} else if (result.decision === "STEP_UP") {
  console.log(`Step-up required. Gates: ${result.gates_fired}`);
  // Request human confirmation, then re-submit
} else if (result.decision === "DECLINE") {
  console.log(`Declined. Reasons: ${result.gates_fired}`);
  console.log(`Recommendations: ${result.recommendations}`);
}

// Query authorization history
const logs = await client.authorization.logs({
  agent_id: "agent_abc123",
  limit: 10,
});
for (const log of logs) {
  console.log(`${log.timestamp} | ${log.decision} | ${log.amount} ${log.currency}`);
}

Next steps