Delegation

Delegation allows a user to authorize an agent to act on their behalf at a specific service. Unlike regular grants (where the agent requests permission for itself), delegations are pre-approved by the delegator.

How It Works

Delegator creates delegation → Grant is auto-approved
                             → Delegate (agent) can use it
                             → Target service sees: "agent acting for delegator"

A delegation grant has type: 'delegation' and includes both the delegator and delegate identities. The target service can distinguish between direct agent actions and delegated actions.

Creating a Delegation

Via CLI

# Delegate to another agent at a specific service
apes grants delegate --to agent@example.com --at api.example.com

# With scopes
apes grants delegate --to agent@example.com --at api.example.com --scopes read,write

# With time limit
apes grants delegate --to agent@example.com --at api.example.com --approval timed --expires 2025-12-31

Via API

POST /api/delegations
{
  "delegate": "agent@example.com",
  "audience": "api.example.com",
  "grant_type": "timed",
  "duration": 86400,
  "scopes": ["read", "write"]
}

The delegation is auto-approved because the delegator (authenticated user) is creating it themselves.

Listing Delegations

# List all delegations (both as delegator and delegate)
apes grants delegations

# JSON output
apes grants delegations --json

The API supports filtering by role:

GET /api/delegations?role=delegator   # delegations you created
GET /api/delegations?role=delegate    # delegations granted to you

Validation

When a delegate uses a delegation grant, the target service validates:

1. The grant exists and is approved
2. The grant type is delegation
3. The delegate identity matches the authenticated agent
4. The audience matches the target service (or is wildcard *)
5. The grant hasn't expired or been revoked

Security Considerations

• Delegations follow the same lifecycle as regular grants (pending, approved, revoked, expired)
• The delegator can revoke a delegation at any time
• Scopes limit what the delegate can do -- omitting scopes means full access at that audience
• Timed delegations auto-expire, reducing the risk of forgotten permissions
• The decided_by field in the AuthZ-JWT shows the delegator, maintaining accountability

Next Steps

• Capabilities & Grants -- the underlying grant system
• escapes -- privilege escalation using grants and delegations