Grants (Reusable Attestations)
A grant is an external attestation with one_time: false. Once approved, it remains active and can satisfy attestation requirements repeatedly without requiring re-approval for each operation.
Grants Are External Attestations
There is no separate "grant" API. Grants use the same list_attestations(),approve_attestation(), and deny_attestation() methods as regular external attestations. The only difference is the one_time setting.
How Grants Work
The motivating use case: when a new agent joins the system, an admin needs to verify and approve it. Without grants, the admin would need to approve every single operation. With a grant (one_time: false), a single approval allows the agent to operate repeatedly.
one_time: true (Default)
Request 1 → Approval → Execute
↓
[Attestation consumed]
↓
Request 2 → Approval → Execute
↓
[Attestation consumed]
↓
Request 3 → Approval → ...Each operation requires a new approval.
one_time: false (Grant)
Admin approves agent (grant)
↓
[Grant remains active]
↓
Request 1 → Grant valid → Execute
Request 2 → Grant valid → Execute
Request 3 → Grant valid → Execute
...Single approval enables repeated operations.
Creating a Grant
Grants are created through the normal attestation approval flow. The key is settingone_time: false in the policy's attestation constraints.
1. Define Policy with Reusable Attestation
{
"policy_id": "team:trading",
"attestations": ["agent_approved"],
"constraints": {
"attestations": {
"agent_approved": {
"approval_criteria": "role:admin",
"one_time": false,
"time_to_live": 86400
}
}
}
}2. Agent Triggers Attestation Request
When the agent first makes a request requiring this attestation, a pending attestation is created:
from macaw_client import MACAWClient
# Agent makes a request that requires 'agent_approved' attestation
client = MACAWClient(app_name="trading-bot")
client.register()
# This will block (or fail) until an admin approves
result = client.invoke_tool("trading", "execute_order", {...})3. Admin Approves (Creates the Grant)
from macaw_client import MACAWClient
# Admin client
admin = MACAWClient(app_name="admin-console")
admin.register()
# List pending attestations that this admin can approve
pending = admin.list_attestations(status="pending")
for att in pending:
print(f"Agent {att['for_agent']} requesting: {att['key']}")
# Approve the attestation (creates a grant since one_time=false)
admin.approve_attestation(pending[0], reason="Agent verified by security team")4. Grant Remains Active
After approval, the agent can make repeated requests without needing re-approval. The grant remains active until it expires (time_to_live) or is manually disabled.
Managing Grants
from macaw_client import MACAWClient
admin = MACAWClient(app_name="admin-console")
admin.register()
# List all attestations (includes active grants)
all_attestations = admin.list_attestations()
# Filter to see only active grants (approved, not one_time)
active_grants = [
att for att in all_attestations
if att['status'] == 'approved' and not att.get('one_time', True)
]
for grant in active_grants:
print(f"Grant: {grant['key']}")
print(f" For agent: {grant['for_agent']}")
print(f" Approved by: {grant['approved_by']}")
print(f" Expires: {grant.get('expires_at', 'Never')}")Revoking a Grant
Grants can be disabled through the Console (Settings → Attestations) or programmatically. Once disabled, the agent will need a new approval.
Via Console
- Go to Activity → Attestations
- Find the grant in the "Active Grants" section
- Click the grant to inspect details
- Click Disable to revoke
Common Use Cases
Agent Onboarding
When a new agent joins the system, admin approves it once. The grant allows the agent to operate within its policy bounds without per-request approval.
Batch Processing
Pre-approve a batch job to run N operations overnight without human intervention for each operation.
Service Account Access
Grant a service account ongoing access to specific resources, with periodic renewal via time_to_live.
Temporary Elevated Access
Grant temporary elevated permissions during an incident or maintenance window, with automatic expiry.
Grant Lifecycle
Agent makes request requiring attestation
│
▼
┌─────────────────────────────────┐
│ Pending │
│ Waiting for admin approval │
└─────────────┬───────────────────┘
│
Admin calls approve_attestation()
│
▼
┌─────────────────────────────────┐
│ Active (Grant) │
│ status: approved │
│ one_time: false │
│ alive: true │
└─────────────┬───────────────────┘
│
Agent makes requests
(grant checked, remains active)
│
▼
┌─────────────────────────────────┐
│ Still Active │
│ Multiple uses allowed │
└─────────────┬───────────────────┘
│
time_to_live expires OR admin disables
│
▼
┌─────────────────────────────────┐
│ Expired / Disabled │
│ alive: false │
│ Agent needs new approval │
└─────────────────────────────────┘Grants vs One-Time Attestations
| Aspect | one_time: true | one_time: false (Grant) |
|---|---|---|
| After approval | Consumed on first use | Remains active |
| Repeated requests | Require new approval each time | Use same grant |
| Expiry | After single use | After time_to_live (or manual disable) |
| Use case | Sensitive one-off operations | Ongoing agent authorization |
| API | Same: list_attestations, approve_attestation, deny_attestation | |
Security Considerations
Always Set time_to_live
Grants without time_to_live remain active indefinitely. Always set a reasonable expiry to limit blast radius if credentials are compromised.
Audit Grant Usage
Monitor attestation_accessed events in the Activity feed to track how often grants are being used and by whom.
Principle of Least Privilege
Use grants for the minimum scope needed. Prefer short time_to_live values and require renewal rather than long-lived grants.