Managing Delegations

What Are Delegations?

A delegation is an authorization grant from a user or service to an AI agent in the KYA-OS 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.

Prerequisites

• A Checkpoint project. See Credentials for how to find your Project ID and API key in Installations.
• To mint or verify delegations directly via the API (rather than through the OAuth flow), an API key with write permission.

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 KYA-OS proofs referencing the delegation
5. Your server verifies proofs → Checkpoint validates the delegation
6. Delegation expires or is revoked

Creating Delegations

Via the OAuth Flow

Delegations are minted by the OAuth integration: the user authorizes the agent via a consent page, and Checkpoint creates the delegation automatically. This is how most delegations come into existence. The dashboard's Delegations page shows every grant created this way — delegations are not created by hand from the dashboard.

Via the API

You can also mint a delegation directly. The endpoint requires an API key with write permission; the project is resolved from the API key itself.

curl -X POST https://kya.vouched.id/api/v1/bouncer/delegations \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -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.10", "203.0.113.11"]
    }
  }'

agent_did and at least one scope are required. Optional fields include agent_name, user_did (the authorizing user's DID), user_id, user_identifier, constraints, expires_in_days (up to 365), metadata, and credential_jwt.

Response (201 Created):

{
  "success": true,
  "data": {
    "delegation_id": "3f2b8c1a-7e4d-4f5b-9a3c-08c1d2e3f4a5",
    "agent_did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "scopes": ["files:read", "files:write"],
    "status": "active",
    "issued_at": "2026-02-01T00:00:00Z",
    "expires_at": "2026-02-08T00:00:00Z",
    "created_at": "2026-02-01T00:00:00Z",
    "delegation_token": "eyJhbGciOiJFZERTQSIs...",
    "token_type": "Bearer",
    "token_format": "vc+jwt",
    "expires_in": 604800
  },
  "metadata": {
    "requestId": "req_abc123",
    "timestamp": "2026-02-01T00:00:00Z"
  }
}

The delegation_token is a W3C Verifiable Credential in JWT format (vc+jwt). Agents can present it for stateless verification — Checkpoint can validate it cryptographically without a database lookup.

Viewing Delegations

The dashboard is the list surface for delegations — there is no public list endpoint on the API. Navigate to Project → Delegations to:

1. See every grant users have authorized for AI agents in the project
2. Filter by status (Active, Expired, Revoked) and search by user, agent, or scope
3. Open a delegation to inspect its scopes, authorization method, activity, and proofs
4. Export the current view as CSV

For programmatic checks against a specific delegation, use the verify endpoint below.

Verifying Delegations

Delegation verification happens automatically when you use @kya-os/bouncer-middleware. When a KYA-OS proof references a delegation, the middleware validates that delegation with Checkpoint.

You can also verify delegations directly. agent_did is required; everything else is optional — pass a delegation_token for stateless verification, or a session_id to resolve the durable session-to-delegation link:

curl -X POST https://kya.vouched.id/api/v1/bouncer/delegations/verify \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "delegation_token": "eyJhbGciOiJFZERTQSIs...",
    "scopes": ["files:read"],
    "client_info": {
      "ip_address": "203.0.113.10",
      "origin": "https://app.example.com"
    }
  }'

Response (200 OK):

{
  "success": true,
  "data": {
    "valid": true,
    "delegation_id": "3f2b8c1a-7e4d-4f5b-9a3c-08c1d2e3f4a5",
    "credential": { "...": "..." }
  },
  "metadata": {
    "requestId": "req_abc123",
    "timestamp": "2026-02-01T00:00:00Z"
  }
}

When verification fails, data.valid is false and data.error carries a code and message explaining why.

Delegation Constraints

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

Revoking Delegations

Revoke a delegation from the dashboard — Project → Delegations, then Revoke delegation on the grant, with an optional revocation reason — or via the API:

curl -X DELETE https://kya.vouched.id/api/v1/bouncer/delegations/{delegationId} \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "User requested"}'

The body is optional — include reason (up to 500 characters) to record why the delegation was revoked.

Response (200 OK):

{
  "success": true,
  "data": {
    "delegation_id": "3f2b8c1a-7e4d-4f5b-9a3c-08c1d2e3f4a5",
    "status": "revoked",
    "revoked_at": "2026-02-03T12:00:00Z",
    "reason": "User requested"
  },
  "metadata": {
    "requestId": "req_abc123",
    "timestamp": "2026-02-03T12:00:00Z"
  }
}

Revocation is idempotent — revoking an already-revoked delegation succeeds and sets was_already_revoked: true in the response. Once revoked, KYA-OS proofs referencing the delegation are rejected with a DELEGATION_REVOKED error.

Delegation Chains

The KYA-OS specification (§8) defines delegation chains — an agent sub-delegating a subset of its permissions to another agent, with cascading revocation up the chain.

Next Steps

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