> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedrock.quarry-systems.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Delegation
> Acting on behalf of other subjects
## What is Delegation?
**Delegation** allows one subject (the **actor**) to perform actions on behalf of another subject (the **principal**). This is essential for AI agents, service accounts, and automated workflows that need to act within a user's permission context.
How actor/principal evaluation works
AI agents acting for users
## Why Delegation Matters
As AI agents become integral to workflows, you need to answer:
* **What can this agent access?** — Agents need scoped permissions
* **Whose permissions apply?** — The agent's, the user's, or both?
* **How do I audit agent actions?** — Track both actor and principal
* **How do I limit agent scope?** — Agents shouldn't exceed user permissions
Bedrock's delegation model addresses all of these.
## The Delegation Model
```
┌─────────────────────────────────────────────────────────┐
│ Evaluation Input │
├─────────────────────────────────────────────────────────┤
│ actor: { subjectId: "agent_123", subjectType: "agent" }│
│ onBehalfOf: { subjectId: "user_jane", subjectType: "user" } │
│ scopeId: "scope_engineering" │
│ action: "read" │
│ resource: { resourceType: "document" } │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Evaluation Logic │
├─────────────────────────────────────────────────────────┤
│ 0. Active delegation grant (actor → principal)? │
│ 1. Does the ACTOR have the permission? │
│ 2. Does the PRINCIPAL have the permission? │
│ 3. All must pass — the allow is the intersection │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Decision │
├─────────────────────────────────────────────────────────┤
│ allowed: true │
│ usedDelegation: true │
│ evaluatedActor: { subjectId: "agent_123", ... } │
│ evaluatedOnBehalfOf: { subjectId: "user_jane", ... } │
└─────────────────────────────────────────────────────────┘
```
Delegation is **gated**: an active [delegation grant](/delegation/on-behalf-of#prerequisite-a-delegation-grant)
authorizing the actor to act for the principal in the scope must exist first, or the request is denied with
`NO_DELEGATION_GRANT` before any permission is checked.
## Basic Example
```typescript theme={null}
// Agent acting on behalf of a user (requires an active delegation grant)
const decision = await bedrock.evaluate({
actor: {
subjectId: "subject_coding_agent",
subjectType: "agent"
},
onBehalfOf: {
subjectId: "subject_jane",
subjectType: "user"
},
scopeId: "scope_engineering",
action: "read",
resource: { resourceType: "document", resourcePattern: "*" }
});
if (decision.allowed) {
console.log("Agent can read documents on behalf of Jane");
console.log("Used delegation:", decision.usedDelegation);
}
```
## Key Concepts
### Actor
The entity actually performing the action. This is typically:
* An AI agent
* A service account
* An automated workflow
* An API integration
### Principal (onBehalfOf)
The entity whose permissions should also be checked. This is typically:
* The human user who initiated the request
* The user who owns the session
* The user who authorized the agent
### Dual Authorization
When `onBehalfOf` is provided, **both** the actor and principal must have the permission:
| Actor Has Permission | Principal Has Permission | Result |
| -------------------- | ------------------------ | --------- |
| ✅ Yes | ✅ Yes | ✅ Allowed |
| ✅ Yes | ❌ No | ❌ Denied |
| ❌ No | ✅ Yes | ❌ Denied |
| ❌ No | ❌ No | ❌ Denied |
The allow is the **intersection** of the two—neither the actor nor the principal can exceed the other. (An active delegation grant must also exist; see the note above.)
## Use Cases
### AI Coding Assistant
```typescript theme={null}
// User asks AI to read a file
const decision = await bedrock.evaluate({
actor: { subjectId: "subject_copilot", subjectType: "agent" },
onBehalfOf: { subjectId: "subject_developer", subjectType: "user" },
scopeId: "scope_repo",
action: "read",
resource: { resourceType: "file", resourcePattern: "*" }
});
```
### Automated Workflow
```typescript theme={null}
// Scheduled job running as a user
const decision = await bedrock.evaluate({
actor: { subjectId: "subject_scheduler", subjectType: "service" },
onBehalfOf: { subjectId: "subject_admin", subjectType: "user" },
scopeId: "scope_org",
action: "export",
resource: { resourceType: "report", resourcePattern: "*" }
});
```
### API Integration
```typescript theme={null}
// Third-party app accessing user data
const decision = await bedrock.evaluate({
actor: { subjectId: "subject_slack_integration", subjectType: "service" },
onBehalfOf: { subjectId: "subject_jane", subjectType: "user" },
scopeId: "scope_workspace",
action: "read",
resource: { resourceType: "message", resourcePattern: "*" }
});
```
## Audit Trail
The decision includes both actor and principal for auditing:
```typescript theme={null}
const decision = await bedrock.evaluate({...});
// Log for audit
console.log({
action: "read",
resource: "document",
actor: decision.evaluatedActor, // The agent
principal: decision.evaluatedOnBehalfOf, // The user
allowed: decision.allowed,
delegationUsed: decision.usedDelegation,
delegationId: decision.delegationId,
timestamp: new Date()
});
```
## Without Delegation
If `onBehalfOf` is not provided, only the actor's permissions are checked:
```typescript theme={null}
// Direct agent action (no delegation)
const decision = await bedrock.evaluate({
actor: { subjectId: "subject_agent", subjectType: "agent" },
scopeId: "scope_org",
action: "read",
resource: { resourceType: "public-data" }
});
// decision.usedDelegation = false
```
## Next Steps
Deep dive into actor/principal evaluation
Patterns for AI agent delegation