Docs/Attestations/External

External Attestations

External attestations require explicit approval from humans or third-party systems. They enable human-in-the-loop workflows, manager approvals, and integration with external verification systems.

Human-in-the-LoopApproval Required

Key Characteristics

Requires Approval

External attestations enter a "pending" state and must be explicitly approved or denied before they can be used. The workflow pauses until approval is received.

approval_criteria Required

Every external attestation must specify approval_criteriawhich defines who is authorized to approve or deny the attestation.

Pending State

Unlike internal attestations that are immediately active, external attestations start in a pending state and transition to approved or denied.

No max_uses

External attestations do not support the max_uses field. Use one_time for single-use behavior.

Fields Reference

Field	Type	Description
key	string	Unique identifier for the attestation
for_agent	string	Target agent this attestation is for
value	any	Arbitrary data stored with the attestation
set_by	string	Identity of who created/signed this attestation
approval_criteria	string	Required. Defines who can approve (e.g., "role:manager")
status	string	"pending", "approved", or "denied"
approved_by	string	Identity of who approved (set after approval)
approved_at	float	Timestamp when approval occurred
one_time	bool	If true, consumed after first use
time_to_live	int	Time-to-live in seconds after approval
polling_timeout	int	How long to wait for approval before timing out
signature	string	Cryptographic signature for verification
invocation_id	string	Links attestation to specific invocation

Required Field

The approval_criteria field is required for external attestations. It defines who is authorized to approve - typically using role-based expressions like role:manager orteam:security.

Lifecycle

                    ┌─────────────────┐
                    │ Request External│
                    │   Attestation   │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │    [Pending]    │
                    │ Waiting for     │
                    │ approval...     │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
┌─────────────┐     ┌─────────────┐      ┌─────────────┐
│  Approved   │     │   Denied    │      │   Expired   │
│ approved_by │     │             │      │  (timeout)  │
│ approved_at │     │             │      │             │
└──────┬──────┘     └─────────────┘      └─────────────┘
       │
       ▼
┌─────────────┐
│   Active    │
│ Can be used │
└──────┬──────┘
       │
       ├──────────────────┐
       │                  │
       ▼                  ▼
┌─────────────┐   ┌─────────────┐
│  Consumed   │   │   Expired   │
│ (one_time)  │   │(time_to_live)│
└─────────────┘   └─────────────┘

External attestations start in a pending state. They must be explicitly approved before becoming active. Approval is tracked with approved_by andapproved_at fields for audit purposes.

Requesting External Attestations

External attestations are created automatically when an agent makes a request that requires an attestation (defined in policy) that doesn't exist yet. The policy must specifyapproval_criteria:

json

{
  "policy_id": "team:trading",
  "attestations": ["manager_approval"],
  "constraints": {
    "attestations": {
      "manager_approval": {
        "approval_criteria": "role:manager",
        "timeout": 3600,
        "one_time": true
      }
    }
  }
}

When an agent makes a request that requires this attestation, the system automatically creates a pending attestation and waits for approval (if timeout > 0).

Workflow Pause

When a request requires an external attestation, the workflow pauses until the attestation is approved, denied, or times out. The timeout parameter controls how long to wait.

Managing with MACAWClient

The MACAWClient provides methods to list, approve, and deny external attestations:

python

from macaw_client import MACAWClient

client = MACAWClient(...)

# List pending attestations
pending = client.list_attestations(status="pending")
print(f"Found {len(pending)} pending attestations")

for att in pending:
    print(f"Key: {att['key']}")
    print(f"Value: {att['value']}")
    print(f"Requested by: {att['set_by']}")
    print(f"Approval criteria: {att['approval_criteria']}")
    print("---")

# Approve an attestation
# (caller must match approval_criteria)
if client.approve_attestation(
    attestation=pending[0],
    reason="Approved per budget guidelines"
):
    print("Attestation approved")

# Deny an attestation
if client.deny_attestation(
    attestation=pending[1],
    reason="Amount exceeds quarterly budget"
):
    print("Attestation denied")

list_attestations()

List attestations visible to this client.

status: "pending" | "approved" | "denied"

approve_attestation()

Approve a pending attestation. Returns True on success.

Requires: match approval_criteria

deny_attestation()

Deny a pending attestation. Returns True on success.

Reason captured for audit

approval_criteria Patterns

The approval_criteria field specifies who can approve the attestation. Common patterns:

Pattern	Description	Example
role:{name}	User must have the specified role	role:manager
team:{name}	User must be in the specified team	team:security
user:{id}	Specific user by identifier	user:alice@corp.com
company:{name}	Any user from the company	company:AcmeCorp

json

// Role-based: Any finance manager can approve
{
  "attestations": ["budget_approval"],
  "constraints": {
    "attestations": {
      "budget_approval": {
        "approval_criteria": "role:finance_manager"
      }
    }
  }
}

// User-specific: Only CEO can approve
{
  "attestations": ["executive_sign_off"],
  "constraints": {
    "attestations": {
      "executive_sign_off": {
        "approval_criteria": "user:ceo@company.com"
      }
    }
  }
}

// Team-based: Any security team member can approve
{
  "attestations": ["security_review"],
  "constraints": {
    "attestations": {
      "security_review": {
        "approval_criteria": "team:security"
      }
    }
  }
}

Common Use Cases

Manager Approvals

High-value operations require manager sign-off before proceeding. The manager reviews the request and approves or denies.

approval_criteria="role:manager"

Security Reviews

Sensitive operations require security team review. Multiple team members can be authorized to approve.

approval_criteria="team:security"

Dual Control

Require multiple attestations from different parties before proceeding with critical operations.

Two attestations: role:manager + role:auditor

External System Integration

Third-party systems can approve attestations via the API, enabling integration with ticketing, approval, or compliance systems.

approval_criteria="system:ticketing"

Comparison with Internal Attestations

Feature	Internal	External
Set by	Tools (automatic)	Humans/systems (explicit)
approval_criteria	Not used	Required
max_uses	Supported	Not used
Pending state	No (immediately active)	Yes (awaits approval)
Workflow behavior	Continues immediately	Pauses until approved