On Behalf Of

Overview

The onBehalfOf field in evaluation requests enables delegated authorization. When provided, Bedrock evaluates permissions for both the actor (who’s performing the action) and the principal (who they’re acting for).

Prerequisite: a Delegation Grant

Delegation is gated. Before any permissions are checked, an active delegation grant authorizing the actor to act for the principal in the scope must exist—otherwise the request is denied with NO_DELEGATION_GRANT. The “both have permission → allowed” logic below applies only once a grant is in place.

curl -X POST 'https://api.example.com/delegation-grants' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "scopeId": "scope_engineering",
    "actorSubjectId": "subject_agent",
    "principalSubjectId": "subject_jane",
    "validFrom": "2026-01-01T00:00:00Z",
    "validUntil": "2026-12-31T23:59:59Z"
  }'

The temporal window (validFrom/validUntil) is checked against a trusted server clock—a forged context.now cannot revive an expired grant.

Evaluation Input

interface BedrockEvaluateInput {
  actor: BedrockSubjectRef;        // Required: who is performing the action
  onBehalfOf?: BedrockSubjectRef;  // Optional: who they're acting for
  scopeId: string;
  action: string;
  resource?: BedrockResourceRef;
  context?: Record<string, unknown>;
}

interface BedrockSubjectRef {
  subjectId: string;
  subjectType: SubjectTypeEnum | string;
}

How Evaluation Works

Without onBehalfOf

Only the actor’s permissions are checked:

const decision = await bedrock.evaluate({
  actor: { subjectId: "subject_jane", subjectType: "user" },
  scopeId: "scope_engineering",
  action: "read",
  resource: { resourceType: "document" }
});

// Checks: Does Jane have "document:read" in scope_engineering?

With onBehalfOf

Both actor AND principal must have the permission:

const decision = await bedrock.evaluate({
  actor: { subjectId: "subject_agent", subjectType: "agent" },
  onBehalfOf: { subjectId: "subject_jane", subjectType: "user" },
  scopeId: "scope_engineering",
  action: "read",
  resource: { resourceType: "document" }
});

// Checks:
// 0. Is there an active delegation grant (agent -> Jane) in scope_engineering?
// 1. Does the agent have "document:read" in scope_engineering?
// 2. Does Jane have "document:read" in scope_engineering?
// 3. All must pass (grant + both legs) — the allow is the intersection

Decision Output

The decision includes delegation details:

interface BedrockDecision {
  allowed: boolean;
  matches: BedrockPermissionMatch[];
  explanation?: string;
  
  // Delegation fields
  usedDelegation?: boolean;        // Was onBehalfOf provided?
  delegationId?: string;           // Reference for audit
  evaluatedActor?: BedrockSubjectRef;
  evaluatedOnBehalfOf?: BedrockSubjectRef;
}

Example Response

{
  allowed: true,
  matches: [
    { permission: {...}, sourceRoleIds: ["role_agent_reader"] },
    { permission: {...}, sourceRoleIds: ["role_editor"] }
  ],
  explanation: "Delegated permission read:document granted. Actor and principal both allowed.",
  usedDelegation: true,
  evaluatedActor: { subjectId: "subject_agent", subjectType: "agent" },
  evaluatedOnBehalfOf: { subjectId: "subject_jane", subjectType: "user" }
}

Permission Scenarios

Scenario 1: Both Have Permission ✅

Agent: Has "document:read" via "Agent Reader" role
Jane:  Has "document:read" via "Editor" role

Result: ALLOWED

Scenario 2: Only Actor Has Permission ❌

Agent: Has "document:read" via "Agent Reader" role
Jane:  Does NOT have "document:read" (Viewer role only has "document:list")

Result: DENIED
Reason: Principal lacks required permission

Scenario 3: Only Principal Has Permission ❌

Agent: Does NOT have "document:read" (no role assignment)
Jane:  Has "document:read" via "Editor" role

Result: DENIED
Reason: Actor lacks required permission

Scenario 4: Neither Has Permission ❌

Agent: No "document:read" permission
Jane:  No "document:read" permission

Result: DENIED
Reason: Neither actor nor principal has permission

Scope Considerations

Both legs are evaluated at the same scopeId, each composed per that scope’s permissionMode. Under the default override mode, each subject needs a membership at that exact scope; under inherit/additive, ancestor grants are pulled in.

const decision = await bedrock.evaluate({
  actor: { subjectId: "subject_agent", subjectType: "agent" },
  onBehalfOf: { subjectId: "subject_jane", subjectType: "user" },
  scopeId: "scope_engineering",
  action: "read",
  resource: { resourceType: "document" }
});

// Both the agent and Jane are resolved at scope_engineering;
// ancestor grants count only if that scope's type is inherit/additive.

Overrides Apply to Both

Scope overrides affect both actor and principal:

# Disable "write" permission in production
curl -X POST 'https://api.example.com/scope-overrides/permissions' \
  -d '{
    "childScopeId": "scope_production",
    "permissionId": "perm_write",
    "state": "inactive"
  }'

// Even if both have "write" normally, it's disabled in production
const decision = await bedrock.evaluate({
  actor: { subjectId: "subject_agent", subjectType: "agent" },
  onBehalfOf: { subjectId: "subject_jane", subjectType: "user" },
  scopeId: "scope_production",
  action: "write",
  resource: { resourceType: "document" }
});

// Result: DENIED (override applies)

Conditional Permissions

Conditions are evaluated for both actor and principal:

# Role-permission edge with a condition (conditions live on the edge, not the permission)
{
  "roleId": "role_reader",
  "permissionId": "perm_doc_read",
  "condition": {
    "==": [{"var": "subject.meta.department"}, "engineering"]
  }
}

// Agent has meta.department = "platform"
// Jane has meta.department = "engineering"
// Document has tags.departments = ["engineering"]

const decision = await bedrock.evaluate({
  actor: { subjectId: "subject_agent", subjectType: "agent" },
  onBehalfOf: { subjectId: "subject_jane", subjectType: "user" },
  scopeId: "scope_org",
  action: "read",
  resource: { resourceId: "resource_eng_doc" }
});

// Agent condition: "platform" in ["engineering"] = false
// Result: DENIED (actor fails condition)

Best Practices

Always use onBehalfOf for user-initiated agent actions

When a user triggers an agent action, include their identity as the principal.

Give agents minimal permissions

Agents should have the minimum permissions needed. Delegation ensures they can’t exceed user permissions.

Log both actor and principal

For audit trails, always log both the actor and principal from the decision.

Consider agent-specific roles

Create roles specifically for agents with appropriate permission sets.

Next Steps

Agent Delegation

Patterns for AI agent delegation

Getting Started

Core Concepts

Resources

Tags

Delegation

Use Cases

Modeling Guides

Overview

Prerequisite: a Delegation Grant

Evaluation Input

How Evaluation Works

Without onBehalfOf

With onBehalfOf

Decision Output

Example Response

Permission Scenarios

Scenario 1: Both Have Permission ✅

Scenario 2: Only Actor Has Permission ❌

Scenario 3: Only Principal Has Permission ❌

Scenario 4: Neither Has Permission ❌

Scope Considerations

Overrides Apply to Both

Conditional Permissions

Best Practices

Next Steps

Agent Delegation

​Overview

​Prerequisite: a Delegation Grant

​Evaluation Input

​How Evaluation Works

​Without onBehalfOf

​With onBehalfOf

​Decision Output

​Example Response

​Permission Scenarios

​Scenario 1: Both Have Permission ✅

​Scenario 2: Only Actor Has Permission ❌

​Scenario 3: Only Principal Has Permission ❌

​Scenario 4: Neither Has Permission ❌

​Scope Considerations

​Overrides Apply to Both

​Conditional Permissions

​Best Practices

​Next Steps

Agent Delegation

Overview

Prerequisite: a Delegation Grant

Evaluation Input

How Evaluation Works

Without onBehalfOf

With onBehalfOf

Decision Output

Example Response

Permission Scenarios

Scenario 1: Both Have Permission ✅

Scenario 2: Only Actor Has Permission ❌

Scenario 3: Only Principal Has Permission ❌

Scenario 4: Neither Has Permission ❌

Scope Considerations

Overrides Apply to Both

Conditional Permissions

Best Practices

Next Steps