What Are Delegations?

A delegation is an authorization grant from a user or service to an AI agent in the MCP-I (Model Context Protocol with Identity) framework. Delegations define:

Who — The agent's DID (Decentralized Identifier)
What — The scopes (permissions) the agent is granted
How long — An expiration time
Under what conditions — Optional constraints (IP restrictions, origin limits, time windows)

Think of delegations as OAuth access tokens for AI agents, with the added guarantee of cryptographic verification.

Delegation Lifecycle

1. User initiates OAuth flow for an AI agent
2. Checkpoint creates a delegation with specified scopes
3. Agent stores the delegation reference
4. Agent creates MCP-I proofs referencing the delegation
5. Your server verifies proofs → Checkpoint validates the delegation
6. Delegation expires or is revoked

Creating Delegations

Via the Dashboard

Navigate to Project → Delegations
Click Create Delegation
Specify the agent DID, scopes, and expiration
Optionally add constraints (IP whitelist, allowed origins)
Save the delegation

Via the API

curl -X POST https://kya.vouched.id/api/v1/bouncer/delegations \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "X-Project-Id: $CHECKPOINT_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "scopes": ["files:read", "files:write"],
    "expires_in_days": 7,
    "constraints": {
      "allowed_origins": ["https://app.example.com"],
      "ip_whitelist": ["203.0.113.0/24"]
    }
  }'

Response:

{
  "success": true,
  "data": {
    "delegation_id": "del_abc123",
    "agent_did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "scopes": ["files:read", "files:write"],
    "status": "active",
    "expires_at": "2026-02-08T00:00:00Z",
    "created_at": "2026-02-01T00:00:00Z"
  }
}

Via OAuth Flow

In production, delegations are typically created through the OAuth integration. The user authorizes the agent via a consent page, and Checkpoint creates the delegation automatically.

Listing Delegations

curl -X GET https://kya.vouched.id/api/v1/bouncer/delegations \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "X-Project-Id: $CHECKPOINT_PROJECT_ID"

Filter by status, agent DID, or scope:

curl -X GET "https://kya.vouched.id/api/v1/bouncer/delegations?status=active&agent_did=did:key:z6Mk..." \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "X-Project-Id: $CHECKPOINT_PROJECT_ID"

Verifying Delegations

Delegation verification happens automatically when you use @kya-os/bouncer-middleware. The middleware extracts the delegation reference from the MCP-I proof and validates it with Checkpoint.

You can also verify delegations directly:

curl -X POST https://kya.vouched.id/api/v1/bouncer/delegations/verify \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "X-Project-Id: $CHECKPOINT_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "delegation_id": "del_abc123",
    "agent_did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "requested_scopes": ["files:read"]
  }'

Delegation Constraints

Delegations support optional constraints that restrict how and where the delegation can be used:

Constraint	Description	Example
`allowed_origins`	Restrict to specific origins	`["https://app.example.com"]`
`ip_whitelist`	Restrict to specific IP ranges	`["203.0.113.0/24"]`
`time_window`	Restrict to specific hours	`{"start": "09:00", "end": "17:00", "timezone": "UTC"}`
`max_uses`	Limit total number of uses	`100`

Constraint violations result in a CONSTRAINT_VIOLATION error (HTTP 403). The agent must obtain a new delegation with appropriate constraints.

Revoking Delegations

Revoke a delegation from the dashboard (Project → Delegations → Revoke) or notify the system via the API:

curl -X POST https://kya.vouched.id/api/v1/bouncer/delegations/notify \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "X-Project-Id: $CHECKPOINT_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "delegation_id": "del_abc123",
    "action": "revoke"
  }'

Once revoked, any MCP-I proofs referencing the delegation will be rejected with a DELEGATION_REVOKED error.

MCP-I supports delegation chains, where an agent can sub-delegate a subset of its permissions to another agent. This enables multi-agent workflows where a primary agent delegates specific tasks to specialized agents.

User → Delegation A (full access) → Primary Agent
  Primary Agent → Delegation B (files:read only) → File Reader Agent

Each link in the chain is independently verifiable, and revoking any link invalidates all downstream delegations.

Next Steps

Proof Verification — How agents use delegations in requests
OAuth Integration — Automated delegation creation via OAuth
Tool Protection — Map delegations to specific tools

Managing Delegations