DocsBuildAPI ReferenceSDK Reference
DocsBuildAPI ReferenceSDK Reference
← Back to Patterns

Revoke Delegation

Availablepassport•intermediate

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 
    {
  "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

    ← All PatternsLearn about passport →