Delegation Flow

Why Delegation Matters

Without delegation, AI agents would require full access to a user's account—posing risks for security, privacy, and compliance.

Delegation in KYA-OS solves this by:

• Scoping authority to only what’s necessary
• Proving user consent cryptographically
• Supporting revocation and expiration
• Allowing audit of each request

Overview

Delegation in KYA-OS follows a structured process that ensures secure, verifiable transfer of authority from principals to agents. This flow encompasses:

1. Identity Preparation: Establishing DIDs for principals and agents
2. Delegation Issuance: Creating and signing delegation credentials
3. Credential Delivery: Securely transferring credentials to agents
4. Credential Usage: Presenting credentials during agent operations
5. Delegation Verification: Validating presented credentials
6. Lifecycle Management: Handling renewal, revocation, and updates

Delegation Lifecycle Diagram

The following diagram shows how a credential is issued, optionally rotated, and eventually revoked:

• A credential may be valid until expiration or actively revoked
• Rotation means a new VC replaces the old one with updated scope or subject
• Verifiers must reject expired or revoked credentials

Delegation Credential Recap

Delegation is encoded in a credential that includes:

• The issuer (user DID)
• The subject (agent DID)
• The scope of allowed actions
• The expiration timestamp
• A cryptographic proof signed by the issuer

→ See Credential Models for the full schema

End-to-End Delegation Process

Consent in KYA-OS is not a separate provisioning ceremony — it is the needs_authorization step-up built into the request path (SPEC.md §9). The agent simply tries to act; the server answers with a signed consent challenge; the principal approves; the agent retries with the credential.

Two properties make this flow safe end to end:

• The needs_authorization challenge is itself signed: its detached proof in _meta carries outcome: "needs_authorization" and a responseHash binding the challenge content, including authorizationUrl. A client verifies that proof against the server's DID before sending its principal anywhere — a substituted consent URL fails the recompute.
• Completing the consent flow is never sufficient by itself. The issued DelegationCredential is still fully verified — chain, signatures, revocation, scope — on the retried request.

Credential Usage Stage

When an agent needs to perform actions, it presents the delegation credential as proof of authority.

Credential Presentation

There is no session establishment and no handshake: every request carries its own material.

1. The agent includes the delegation credential (or chain) with the tool call — in the reference middleware, via the reserved _kyaos_delegation argument; on outbound HTTP calls, via the KYA-OS-Delegation-Credential header
2. The request carries a per-request holder-of-key proof signed by the delegate's key — the card-era carrier is _meta["org.kya-os/request-proof"] — so a captured credential is inert to anyone who does not hold the key
3. The invocation designates the specific scope being exercised; multi-scope delegations cannot be used without designation (SPEC.md §6.4.1)

Delegation Verification Stage

Every service verifies for itself, in its own process, on every request.

Verification Steps

1. Structural Validation: Ensure the credential has all required fields — including the strict credentialSubject shape (only id + delegation)
2. DID Resolution: Resolve the DIDs of the issuer and the delegate
3. Signature Verification: Validate each credential's cryptographic proof against its issuer's keys
4. Temporal Check: Confirm the credential is within its validity window
5. Revocation Check: Confirm no credential in the chain is revoked — evaluated on every verification
6. Chain and Attenuation Check: For chains, confirm every hop attenuates its parent (continuity, scope subsets, validity narrowing)
7. Scope Designation Check: Ensure the designated action is within the delegated scope
8. Constraints Validation: Check the CRISP constraint envelope (audience, budgets, extended scopes) against the request context

Performance Optimizations

For high-volume services:

• Cache DID resolution results
• Cache signature validity only: revocation status and expiry are evaluated on every verification, and verdicts are never cached (the v1.13.0 security fix)
• Bound status-list staleness explicitly with withStatusCache(resolver, { maxStalenessMs }) if your deployment needs it, rather than ad-hoc TTL caching of results
• Use parallel processing for verification steps when possible

Delegation Lifecycle Management

Throughout a delegation's lifecycle, several events may require updates or changes.

Credential Renewal

When a credential approaches expiration:

1. The principal initiates renewal (manually or automatically)
2. A new credential is issued with an updated expiration date
3. The agent replaces the old credential with the new one
4. Optionally, the old credential may be explicitly revoked

Credential Revocation

When a delegation needs to be withdrawn:

1. An authorized party requests revocation — the direct issuer, any ancestor issuer, or the Responsible Party at the root; a delegate cannot revoke its own delegation
2. The status list (StatusList2021 in the legacy era, Bitstring Status List in the card era) is updated, and revocation cascades: every descendant delegation is revoked with it
3. Verifiers detect the revocation on their next verification — status is checked every time
4. Short-lived credentials bound the propagation window; explicit revocation signals are honored immediately

Delegation Updates

When delegation parameters need to change:

1. The principal initiates an update
2. A new credential is issued with modified parameters
3. The old credential is revoked
4. The agent receives and begins using the new credential

Implementation Examples

Protecting a Tool (Server Side)

The server declares which tools require delegation; the step-up flow above happens automatically:

import { withKyaOs, NodeCryptoProvider } from "@kya-os/mcp";

const kyaos = await withKyaOs(server, { crypto: new NodeCryptoProvider() });

const placeOrder = kyaos.wrapWithDelegation(
  "place_order",
  {
    scopeId: "orders:write",
    consentUrl: "https://example.com/consent",
  },
  kyaos.wrapWithProof("place_order", async (args) => ({
    content: [{ type: "text", text: `Order placed: ${args["item"]}` }],
  }))
);

Issuing a Delegation (Authorization Service Side)

When the principal approves, the authorization service issues the credential:

import { createDelegationIssuer } from "@kya-os/mcp/delegation";

const issuer = createDelegationIssuer(identity, signVc);

const credential = await issuer.createAndIssueDelegation({
  id: "del-001",
  issuerDid: principalDid,
  subjectDid: agentDid,
  constraints: {
    scopes: ["orders:write"],
    notAfter: Math.floor(Date.now() / 1000) + 86_400,
    audience: serverDid,
  },
});

The agent then retries the original call with the resumeToken and the new credential, and the server verifies and executes.

Special Delegation Scenarios

Multi-level Delegation

For scenarios involving delegation chains:

1. The original principal delegates to Agent A
2. Agent A sub-delegates a subset of its authority to Agent B
3. Each hop references its parent by identifier, and the verifier recomputes the whole chain — see Chained Credential

Constrained Delegations

For delegations with advanced constraints:

1. The credential carries the CRISP constraint envelope — temporal bounds, audience, extended scopes with matchers, budgets
2. Verification evaluates these constraints against the request context
3. Chained delegations must narrow, never broaden, their parent's constraints

Next Steps

• Explore the Verification Protocol for detailed verification procedures
• Learn about Audit Layer for tracking delegation activities