Revoke Delegation

Overview

Instantly revoke an agent's delegated access, terminating its authority to act on your behalf. Revocation is immediate, cryptographically enforced, and recorded on the immutable provenance ledger.

Why Revoke Delegations?

Security Response: Immediately terminate access if an agent is compromised
Scope Change: End a delegation when a task is complete or no longer needed
Trust Violation: Revoke if an agent acts outside its authorized scope
Compliance: Meet audit requirements for access termination
Zero Latency: Revocation is instant—no polling, no delays

Think of it like: Canceling a credit card the moment you suspect fraud—instant, irreversible, and auditable.

SDK Examples

SDK:

REST API Example

POST /v1/passport/grants/{grant_id}/revoke
Content-Type: application/json
Authorization: Bearer <DELEGATION_TOKEN>

{
  "reason": "Task completed"
}

Response (200 OK):

{
  "grant_id": "del_a1b2c3d4e5f6",
  "grant_type": "delegation",
  "status": "revoked",
  "revoked_at": "2026-01-10T12:00:00Z",
  "revoked_by": "did:human:alice-smith",
  "reason": "Task completed"
}

Use Cases

1. Emergency Revocation

Scenario: An agent is compromised—revoke every active grant you issued to that delegatee.

import { HumanClient } from '@human/sdk';

async function emergencyRevoke(
  client: HumanClient,
  agentDid: string,
  reason: string,
) {
  const { data: grants } = await client.passport.grants.list({
    kind: 'delegation',
    status: 'active',
    limit: 100,
  });

  const targets = grants.filter((g) => g.delegatee_did === agentDid);
  await Promise.all(
    targets.map((g) =>
      client.passport.grants.revoke(g.grant_id, `EMERGENCY: ${reason}`),
    ),
  );
  console.log(`Revoked ${targets.length} grants for ${agentDid}`);
}

2. Time-Bound Task Completion

Scenario: Task finished—revoke the grant instead of waiting for expiry.

async function finishAndRevoke(
  client: HumanClient,
  grantId: string,
  invoiceId: string,
) {
  try {
    // …process invoice…
    await client.passport.grants.revoke(
      grantId,
      `Invoice ${invoiceId} processed successfully`,
    );
  } catch (err) {
    await client.passport.grants.revoke(
      grantId,
      `Invoice processing failed: ${err instanceof Error ? err.message : String(err)}`,
    );
    throw err;
  }
}

3. Scope Violation Detection

Scenario: Attempted action outside authorized scopes—revoke immediately.

async function enforceScope(
  client: HumanClient,
  action: string,
  grant: { grant_id: string; scopes: string[]; delegatee_did: string },
) {
  if (!grant.scopes.includes(action)) {
    await client.passport.grants.revoke(
      grant.grant_id,
      `Scope violation: attempted '${action}' but only authorized for [${grant.scopes.join(', ')}]`,
    );
    throw new Error(`Scope violation: '${action}' not authorized`);
  }
  return true;
}

Revocation in Delegation Chains

When you revoke a grant in a chain, downstream authority derived from that grant is invalidated. Prefer explicit revoke of the parent grant you issued:

await client.passport.grants.revoke(
  seniorGrantId,
  'Restructuring team',
);
// Downstream agents that depended on the senior grant lose effective authority.

Provenance Chain After Revocation:

Alice [Human] → Acme Corp [Org] → ~~Senior Agent~~ (REVOKED) → ~~Junior Agent~~ (CASCADED REVOCATION)

All downstream delegations are invalidated to prevent orphaned authority.

Security Considerations

DO:

Revoke immediately when a task is complete (principle of least privilege duration)
Log revocation reasons for audit trails
Monitor for repeated revocations (may indicate agent issues)
Use cascade revocation to clean up delegation chains
Set up alerts for emergency revocations

DON'T:

Delay revocation "just in case" (increases attack surface)
Revoke without logging a reason (hurts auditability)
Assume expiration is sufficient (explicit revocation is always better)
Forget to handle revocation errors (they're rare but possible)

Provenance & Auditability

Every revocation is permanently recorded on the distributed ledger:

{
  "eventType": "delegation_revoked",
  "delegationId": "delegation:human:a1b2c3d4e5f6...",
  "revokerDid": "did:human:alice-smith",
  "revokedAt": "2026-01-10T12:00:00Z",
  "reason": "Task completed",
  "ledgerSignature": "0x7b3f9a2c...",
  "cascadeRevocations": 2 // If delegation chain
}

This creates an immutable audit trail for compliance, security reviews, and forensics.

Security Breach Response

Immediately revoke agent access upon detecting suspicious activity or compromise

Task Completion

Automatically revoke delegation when a specific task or project is finished

Employee Offboarding

Instantly terminate all delegated access when an employee leaves the organization

Agent Rotation

Revoke and re-delegate when upgrading or replacing an agent

DO

Log revocation reasons for audit trails and compliance

Notify affected agents when their access is revoked

Check for delegation chains and revoke sub-delegations automatically

Use revocation lists (CRLs) for offline verification scenarios

DON'T

Delay revocation processing - every second counts in security incidents

Allow revokers without proper authority - verify grantor identity

Skip ledger anchoring - revocations must be immutably recorded

Forget to clean up cached tokens and sessions after revocation