Authenticated Workflows
Every invocation between agents, tools, and LLMs is cryptographically signed by the sender and independently verified by the receiver. Policy enforcement happens at the endpoint, creating a tamper-proof audit trail.
Invocation Flow
The receiver verifies independently using the caller's public key from the Agent Registry. Even a compromised caller cannot forge signatures or bypass policy—the receiver has full authority to accept or reject.
Independent Verification
The receiver doesn't trust the caller's claims—it verifies them independently. Policy evaluation considers multiple perspectives:
- •Organizational hierarchy — what's allowed at org/team level
- •App permissions — what this app is authorized to do
- •User/tool scope — what the user or tool can access
- •Caller's intent — what the caller declared they want to do
# At the receiver, verification happens automatically
# The SDK handles all cryptographic operations
@tool.handler("database/query")
def handle_query(invocation: Invocation) -> dict:
# By the time your handler runs:
# 1. Signature verified ✓
# 2. Identity confirmed ✓
# 3. Policy evaluated ✓
# Invocation includes verified caller info
caller = invocation.caller_id
permissions = invocation.verified_permissions
# Your handler just processes the request
return execute_query(invocation.arguments)What Gets Signed
The signature covers all security-relevant parts of the invocation, preventing tampering:
Request Signature
- • Tool/resource name
- • All parameters
- • Caller identity
- • Timestamp
- • Nonce (replay protection)
- • Intent policy (declared permissions)
Response Signature
- • Result data
- • Executor identity
- • Request reference
- • Timestamp
- • Policy decision (allow/deny)
- • Audit entry ID
Both request and response are signed, creating a dual-signature pattern. This proves what was requested, who requested it, what was returned, and who executed it.
Security Properties
| Property | Guarantee |
|---|---|
| Non-repudiation | Signatures prove who performed each action |
| Integrity | Any tampering invalidates the signature |
| Replay protection | Nonce + timestamp window prevents replay attacks |
| Complete coverage | All operations verified before execution |
| No false negatives | Every policy violation is caught |
Integration
The SDK handles signing and verification automatically. Your code focuses on business logic while MACAW ensures every call is secure.
Policy violations throw PermissionDenied with details about which rule was violated.
from macaw_client import MACAWClient, PermissionDenied
client = MACAWClient(app_name="my-app")
client.register()
# Every invocation is signed, verified, policy-evaluated
try:
result = client.invoke_tool(
tool_name="database/query",
arguments={"query": "SELECT * FROM users"}
)
except PermissionDenied as e:
print(f"Blocked: {e.reason}")
print(f"Policy: {e.policy_rule}")
client.unregister()Audit Trail
Every invocation—whether allowed or denied—is logged with full context. The audit entry includes:
- • Caller and executor identities
- • Full request parameters
- • Policy decision and reasoning
- • Cryptographic signatures
- • Timestamps with microsecond precision
{
"event_type": "tool_invocation",
"timestamp": "2024-01-15T10:23:45.123456Z",
"caller_id": "agent:my-app",
"tool": "database/query",
"arguments": {"query": "SELECT..."},
"policy_decision": "allow",
"policy_rules_matched": ["rule:analyst-read"],
"signature": "ed25519:abc123...",
"audit_id": "audit:789xyz"
}