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

typescript:TypeScript
```typescript
import { HumanOS } from '@human/sdk';

async function revokeDelegation(
  revokerPassportDid: string,
  delegationId: string
) {
  try {
    const revocation = await HumanOS.Passport.revokeDelegation({
      revokerDid: revokerPassportDid,
      delegationId: delegationId,
      reason: "Task completed", // Optional: audit trail
    });
    
    console.log(`Delegation ${delegationId} revoked successfully`);
    console.log(`Revoked at: ${revocation.revokedAt}`);
    console.log(`Revocation recorded on ledger: ${revocation.ledgerProof}`);
    
    return revocation;
  } catch (error) {
    console.error("Failed to revoke delegation:", error);
    throw error;
  }
}

// Example usage:
const humanDid = "did:human:alice-smith";
const delegationId = "delegation:human:a1b2c3d4e5f6...";
revokeDelegation(humanDid, delegationId);
```

python:Python
```python
from human_sdk import HumanOS
from datetime import datetime

async def revoke_delegation(
    revoker_passport_did: str,
    delegation_id: str
):
    try:
        revocation = await HumanOS.Passport.revoke_delegation(
            revoker_did=revoker_passport_did,
            delegation_id=delegation_id,
            reason="Task completed"  # Optional: audit trail
        )
        
        print(f"Delegation {delegation_id} revoked successfully")
        print(f"Revoked at: {revocation.revoked_at}")
        print(f"Revocation recorded on ledger: {revocation.ledger_proof}")
        
        return revocation
    except Exception as e:
        print(f"Failed to revoke delegation: {e}")
        raise

# Example usage:
human_did = "did:human:alice-smith"
delegation_id = "delegation:human:a1b2c3d4e5f6..."
# await revoke_delegation(human_did, delegation_id)
```

go:Go
```go
package main

import (
    "fmt"
    "github.com/human/sdk-go/humanos"
)

func revokeDelegation(revokerDID, delegationID string) (*humanos.Revocation, error) {
    revocation, err := humanos.Passport.RevokeDelegation(&humanos.RevokeRequest{
        RevokerDID: revokerDID,
        DelegationID: delegationID,
        Reason: "Task completed",
    })
    if err != nil {
        return nil, fmt.Errorf("failed to revoke delegation: %w", err)
    }
    
    fmt.Printf("Delegation %s revoked successfully\n", delegationID)
    fmt.Printf("Revoked at: %s\n", revocation.RevokedAt)
    fmt.Printf("Ledger proof: %s\n", revocation.LedgerProof)
    
    return revocation, nil
}

// Example usage:
// humanDID := "did:human:alice-smith"
// delegationID := "delegation:human:a1b2c3d4e5f6..."
// revokeDelegation(humanDID, delegationID)
```

REST API Example

DELETE /v1/passport/delegation/{delegationId}
Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY_OR_OAUTH_TOKEN>

{
  "revokerDid": "did:human:alice-smith",
  "reason": "Task completed",
  "timestamp": "2026-01-10T12:00:00Z"
}

Response (200 OK):

{
  "delegationId": "delegation:human:a1b2c3d4e5f6...",
  "status": "revoked",
  "revokedAt": "2026-01-10T12:00:00Z",
  "revokedBy": "did:human:alice-smith",
  "ledgerProof": "0x7b3f9a2c...",
  "reason": "Task completed"
}

Use Cases

1. Emergency Revocation

Scenario: An agent is compromised or behaving unexpectedly—immediate termination required.

typescript:TypeScript
```typescript
// Security team detects anomalous behavior
async function emergencyRevoke(agentDid: string, reason: string) {
  // Get all active delegations for this agent
  const delegations = await HumanOS.Passport.listDelegations({
    delegateeDid: agentDid,
    status: 'active'
  });
  
  // Revoke all delegations immediately
  const revocations = await Promise.all(
    delegations.map(d => 
      HumanOS.Passport.revokeDelegation({
        revokerDid: d.grantorDid,
        delegationId: d.id,
        reason: `EMERGENCY: ${reason}`
      })
    )
  );
  
  console.log(`Revoked ${revocations.length} delegations for ${agentDid}`);
  
  // Alert security team
  await alertSecurityTeam({
    agentDid,
    reason,
    revocations: revocations.length
  });
}

// Example usage:
emergencyRevoke(
  "did:human:agent:suspicious-bot",
  "Detected unauthorized data access attempt"
);
```

python:Python
```python
# Security team detects anomalous behavior
async def emergency_revoke(agent_did: str, reason: str):
    # Get all active delegations for this agent
    delegations = await HumanOS.Passport.list_delegations(
        delegatee_did=agent_did,
        status='active'
    )
    
    # Revoke all delegations immediately
    revocations = await asyncio.gather(*[
        HumanOS.Passport.revoke_delegation(
            revoker_did=d.grantor_did,
            delegation_id=d.id,
            reason=f"EMERGENCY: {reason}"
        )
        for d in delegations
    ])
    
    print(f"Revoked {len(revocations)} delegations for {agent_did}")
    
    # Alert security team
    await alert_security_team({
        'agent_did': agent_did,
        'reason': reason,
        'revocations': len(revocations)
    })

# Example usage:
# await emergency_revoke(
#     "did:human:agent:suspicious-bot",
#     "Detected unauthorized data access attempt"
# )
```

2. Time-Bound Task Completion

Scenario: An agent completes its assigned task—no need to wait for expiration.

typescript:TypeScript
```typescript
// Agent completes invoice processing
class InvoiceAgent {
  async processInvoice(invoice: Invoice, delegation: Delegation) {
    try {
      // Process the invoice
      const result = await this.process(invoice);
      
      // Task complete - immediately revoke delegation
      await HumanOS.Passport.revokeDelegation({
        revokerDid: delegation.grantorDid,
        delegationId: delegation.id,
        reason: `Invoice ${invoice.id} processed successfully`
      });
      
      console.log(`Task complete. Delegation auto-revoked.`);
      return result;
    } catch (error) {
      // On error, also revoke (no retries needed)
      await HumanOS.Passport.revokeDelegation({
        revokerDid: delegation.grantorDid,
        delegationId: delegation.id,
        reason: `Invoice processing failed: ${error.message}`
      });
      throw error;
    }
  }
}
```

python:Python
```python
# Agent completes invoice processing
class InvoiceAgent:
    async def process_invoice(self, invoice: Invoice, delegation: Delegation):
        try:
            # Process the invoice
            result = await self.process(invoice)
            
            # Task complete - immediately revoke delegation
            await HumanOS.Passport.revoke_delegation(
                revoker_did=delegation.grantor_did,
                delegation_id=delegation.id,
                reason=f"Invoice {invoice.id} processed successfully"
            )
            
            print("Task complete. Delegation auto-revoked.")
            return result
        except Exception as error:
            # On error, also revoke (no retries needed)
            await HumanOS.Passport.revoke_delegation(
                revoker_did=delegation.grantor_did,
                delegation_id=delegation.id,
                reason=f"Invoice processing failed: {str(error)}"
            )
            raise
```

3. Scope Violation Detection

Scenario: An agent attempts an action outside its authorized scope—automatic revocation.

typescript:TypeScript
```typescript
// Middleware: Detect and revoke on scope violation
async function enforceScope(
  action: string,
  delegation: Delegation
) {
  const allowedScopes = delegation.scopes;
  
  if (!allowedScopes.includes(action)) {
    // Scope violation detected - immediate revocation
    await HumanOS.Passport.revokeDelegation({
      revokerDid: delegation.grantorDid,
      delegationId: delegation.id,
      reason: `Scope violation: attempted '${action}' but only authorized for [${allowedScopes.join(', ')}]`
    });
    
    // Log security event
    await securityLog({
      severity: 'HIGH',
      event: 'scope_violation',
      agentDid: delegation.delegateeDid,
      attemptedAction: action,
      authorizedScopes: allowedScopes,
      delegationRevoked: true
    });
    
    throw new Error(`Scope violation: '${action}' not authorized`);
  }
  
  // Scope valid - proceed
  return true;
}
```

python:Python
```python
# Middleware: Detect and revoke on scope violation
async def enforce_scope(
    action: str,
    delegation: Delegation
):
    allowed_scopes = delegation.scopes
    
    if action not in allowed_scopes:
        # Scope violation detected - immediate revocation
        await HumanOS.Passport.revoke_delegation(
            revoker_did=delegation.grantor_did,
            delegation_id=delegation.id,
            reason=f"Scope violation: attempted '{action}' but only authorized for [{', '.join(allowed_scopes)}]"
        )
        
        # Log security event
        await security_log({
            'severity': 'HIGH',
            'event': 'scope_violation',
            'agent_did': delegation.delegatee_did,
            'attempted_action': action,
            'authorized_scopes': allowed_scopes,
            'delegation_revoked': True
        })
        
        raise Exception(f"Scope violation: '{action}' not authorized")
    
    # Scope valid - proceed
    return True
```

Revocation in Delegation Chains

When you revoke a delegation in a chain, all downstream delegations are automatically revoked.

typescript:TypeScript
```typescript
// Manager → Senior Agent → Junior Agent → Action

// Manager revokes Senior Agent's delegation
await manager.revokeDelegation({
  delegationId: seniorDelegation.id,
  reason: "Restructuring team"
});

// Result: Both Senior Agent AND Junior Agent lose access
// Junior Agent's delegation is automatically cascaded-revoked
```

python:Python
```python
# Manager → Senior Agent → Junior Agent → Action

# Manager revokes Senior Agent's delegation
await manager.revoke_delegation(
    delegation_id=senior_delegation.id,
    reason="Restructuring team"
)

# Result: Both Senior Agent AND Junior Agent lose access
# Junior Agent's delegation is automatically cascaded-revoked
```

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.

shield:Security Breach Response|Immediately revoke agent access upon detecting suspicious activity or compromise
zap:Task Completion|Automatically revoke delegation when a specific task or project is finished
building:Employee Offboarding|Instantly terminate all delegated access when an employee leaves the organization
bot:Agent Rotation|Revoke and re-delegate when upgrading or replacing an agent

do:Log revocation reasons for audit trails and compliance
do:Notify affected agents when their access is revoked
do:Check for delegation chains and revoke sub-delegations automatically
do:Use revocation lists (CRLs) for offline verification scenarios
dont:Delay revocation processing - every second counts in security incidents
dont:Allow revokers without proper authority - verify grantor identity
dont:Skip ledger anchoring - revocations must be immutably recorded
dont:Forget to clean up cached tokens and sessions after revocation

Next Steps

• Learn how to Verify Delegations Offline
• Understand Delegation Chains
• Explore Provenance Tracking

---

See Also

• Concept Doc: Delegation
• API Reference: Revoke Delegation API
• SDK Reference: Passport.revokeDelegation()