Delegations

Secure, Constrained Access for AI Agents

What is a Delegation?

A Delegation is a secure token that allows one Passport to act on behalf of another — with specific constraints.

Think of it as OAuth for AI agents — you grant an agent permission to act on your behalf, but you control:

Scope

What the agent can do

Expiration

When access ends

Usage Limits

How many times it can act

Why Delegations Matter

The Problem with Traditional Access Control

API keys are all-or-nothing — give an agent your key, it has full access forever

No audit trail — can't tell who did what on whose behalf

No expiration — access never ends unless you manually revoke it

Delegations Fix This

Scoped permissions — agent can only do specific things

Automatic expiration — access ends on a specific date or after N uses

Full provenance — every action is logged with delegation context

Create a Delegation

SDK:

Key Components

Delegation ID

A unique identifier for the delegation. Format: delegation_abc123

typescript

delegationId: "delegation_alice_to_agent_2024"

Delegation Token

A cryptographic token the agent uses to authenticate. This proves the agent is acting on behalf of the delegator.

typescript

token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Scope

The capabilities the agent can exercise. Acts as a filter on top of the agent's declared capabilities.

typescript

scope: ['invoice_processing', 'pdf_extraction']

// Agent can ONLY use these capabilities, even if it has others

Constraints

Rules that limit how the delegation can be used:

Constraint	Description
expiresAt	Date/time when delegation expires
maxUses	Maximum number of times delegation can be used
allowedOperations	Operations the agent can perform (e.g., read, write, delete)
ipWhitelist	Restrict to specific IP addresses
timeWindow	Only allow during specific hours (e.g., business hours)

Use a Delegation

The agent uses the delegation token to authenticate when making API calls:

SDK:

Revoke a Delegation

If you need to immediately revoke access (e.g., agent misbehaves, employee leaves):

SDK:

Common Patterns

Short-Lived Delegations

For one-off tasks, create a delegation that expires in a few hours or after a single use.

typescript

constraints: {
  expiresAt: new Date(Date.now() + 3600000).toISOString(), // 1 hour
  maxUses: 1 // Single use
}

Read-Only Delegations

For analytics or reporting agents, grant read-only access.

typescript

constraints: {
  allowedOperations: ['read'] // No write, delete, or modify
}

Business Hours Only

Restrict agent access to specific time windows (e.g., 9am-5pm weekdays).

typescript

constraints: {
  timeWindow: {
    days: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'],
    startHour: 9,
    endHour: 17,
    timezone: 'America/New_York'
  }
}

Common Use Cases

Employee Delegation

Employee delegates to an assistant agent for routine tasks (email, scheduling, data entry)

Org-Wide Delegation

Organization delegates to approved agents for all employees

Temporary Access

Contractor gets 90-day delegation, auto-expires when project ends

Emergency Revocation

If agent misbehaves or is compromised, instantly revoke all delegations

Audit & Compliance

Prove who delegated what to whom, when, and under what constraints

Learn More

Track delegation usage