Capabilities & Grants

OpenApe agents start with zero permissions. Every action requires an explicit, human-approved grant. This page explains how the grant system works end-to-end.

Core Concept

The grant system implements a human-in-the-loop authorization model:

Agent requests permission → Grant is created (pending)
                          → Human reviews and decides
                          → Agent receives AuthZ-JWT (if approved)
                          → Agent uses token for authorized action

Grant Types

Requesting a Grant

Via CLI

# Adapter mode: wraps a CLI command with grant protection
apes run -- kubectl apply -f deployment.yaml

# With explicit approval type
apes run --approval timed -- npm publish

# Audience mode: request a grant for a specific target
apes run escapes "apt-get upgrade"

Via API

POST /api/grants
{
  "requester": "agent@example.com",
  "target_host": "prod-server",
  "audience": "escapes",
  "grant_type": "once",
  "command": ["apt-get", "upgrade"],
  "reason": "Security patch"
}

Approval Flow

When a grant is requested, the CLI prints an approval URL:

Grant requested: 3f8a...
Approve at: https://id.openape.ai/grant-approval?grant_id=3f8a...

The approver (agent owner or designated approver) opens this URL and sees:

• Who is requesting (agent identity)
• What they want to do (command, target host)
• Why (reason field)

The approver can:

• Approve with the requested type, or override to a different type/duration
• Deny the request

AuthZ-JWT

On approval, a signed JWT is issued containing:

{
  "sub": "agent@example.com",
  "aud": "target-system",
  "grant_type": "once",
  "permissions": ["deploy"],
  "cmd_hash": "sha256:a1b2c3...",
  "decided_by": "alice@example.com",
  "exp": 1234567890,
  "jti": "unique-grant-id"
}

Security properties:

• Audience-bound -- token only valid for the intended target system
• Command hash -- binds to the exact command, prevents substitution attacks
• Dual accountability -- agent requester and human approver are both recorded
• Replay protection -- unique jti per grant, once grants are consumed on use

Incremental Capabilities

When an agent already has a grant for a similar action, the system detects this and offers the approver two options:

• Widen -- expand the existing grant's scope to cover the new request
• Merge -- combine the permission sets of old and new grants

This avoids grant sprawl while maintaining the principle of least privilege.

Managing Grants

# List your grants
apes grants list

# Check grant inbox (pending approvals)
apes grants inbox

# Revoke a specific grant
apes grants revoke <grant-id>

# Revoke all your pending grants
apes grants revoke --all-pending

Next Steps

• Delegation -- let agents act on behalf of another user
• escapes -- privilege escalation with grant verification
• Grant API reference -- full API details