Delegate Access to an Agent

Overview

Grant an AI agent permission to act on your behalf with specific, time-bound, and revocable constraints. Delegation is how you give agents the authority to perform tasks while maintaining full control and accountability.

Human Passports: how delegation is signed

Your primary Passport auth key stays on the device (WebAuthn). The API cannot pretend it has that key. So when documentation shows delegation mint, there are supported ways to obtain a signed delegation JWT:

1. Interactive: Complete WebAuthn, then exchange your session at POST /v1/sessions/delegation-tokens for a delegation token.
2. Programmatic (automation / CI): While logged in with a live session, call POST /v1/passports/:id/api-signing-keys with a label to create a Human API Signing Key (server-held, KEK-encrypted, revocable). Later, call POST /v1/passports/:id/delegate with optional signing_key_id.
3. CLI intent mint: human delegation mint → POST /v1/delegation-tokens (requires an existing authenticated delegation).

These keys only sign delegation JWTs — they are not your WebAuthn identity key. Revoke a key with DELETE /v1/passports/:id/api-signing-keys/:keyId when a pipeline is retired.

What is Delegation?

Delegation in HUMΛN means:

• Explicit authorization - The agent can only do what you explicitly permit
• Time-bound - Delegations expire automatically
• Revocable - You can revoke access at any time (client.passport.grants.revoke)
• Auditable - Every action the agent takes is logged and signed

Think of it like: Giving someone power of attorney, but cryptographically enforced and instantly revocable.

SDK Examples

How Agents Use Delegation

Once minted, pass the JWT as Authorization: Bearer on every API call (or construct HumanClient with delegationToken):

Use Cases

1. Enterprise Automation

Scenario: Finance team needs an agent to process invoices under scoped authority.

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

const client = new HumanClient({
  delegationToken: process.env.HUMAN_DELEGATION_TOKEN!,
});

const { data, error } = await client.raw.POST(
  `/v1/passports/${encodeURIComponent(process.env.HUMAN_PASSPORT_DID!)}/delegate`,
  {
    body: {
      toPassportId: 'did:agent:finance-processor',
      scope: ['invoices:process', 'payments:initiate'],
      conditions: {
        environment: 'production',
        riskLevel: 'high',
        maxUses: 100,
      },
    },
  },
);
if (error) throw error;

2. Personal Assistant (CLI mint)

Scenario: Short-lived scopes for a personal assistant agent.

human delegation mint \
  --scope companion:chat \
  --scope calendar:read \
  --to did:agent:personal-assistant \
  --duration 7d \
  --yes

3. Inspect & revoke

const { data: grants } = await client.passport.grants.list({
  kind: 'delegation',
  status: 'active',
  limit: 20,
});
await client.passport.grants.revoke(grants[0]!.grant_id, 'Task completed');

Security Considerations

Scope vocabulary

Delegations are only as safe as their named scopes. Prefer packages from the Canon vocabulary (kb/175, generated packages/core/src/generated/delegation-scopes.ts) over ad-hoc strings:

Package / scope family	Typical use
cp-operator.read	Command Plane read
human_api:agents:invoke	Invoke agents under policy
companion:chat	Companion conversation
kb:read:*	Classified KB read (tier-gated)

# Mint with a known package (CLI → POST /v1/delegation-tokens)
human delegation mint --package cp-operator.read --to did:agent:ops-bot --yes

# Or explicit scopes from the vocabulary
human delegation mint \
  --scope human_api:agents:invoke \
  --scope kb:read:internal \
  --to did:agent:research-bot \
  --duration 24h \
  --yes

Alias URLs: /docs/patterns/passport/delegation, /docs/patterns/mcp/scope-vocabulary, and /docs/patterns/humanos/delegation-pattern resolve to this page’s delegation model.

Passport with delegations

A Passport holds identity; delegations are the grants that let agents act. Creating a Passport does not imply authority — mint scopes as above, then revoke with client.passport.grants.revoke when the task ends. See also Create Passport and Revoke Delegation.

Next Steps

• Learn how to Revoke Delegation
• Understand Verify Offline
• Explore Human-in-the-Loop
• Capability routing

---

See Also

• Concept Doc: Delegation
• CLI: human delegation mint
• Passport grants (SDK)
• Community: Delegation scope vocabulary