Agent authorization

Agent Authorization

When to Use

Use when AI agents, LLM tool calls, MCP servers, or automated bots invoke application APIs, query databases, or trigger business workflows on behalf of users or workspaces.

Core Rule: Dual-Principal Intersection (Never a Confused Deputy)

An AI agent is never an all-powerful root user. When an agent runs on behalf of a human user (delegator), its effective permission is the strict intersection of two scopes: $$\text{Effective Permission} = \text{Permissions}(\text{Delegating User}) \cap \text{Declared Scope}(\text{Agent / Tool})$$

1. The Agent Cannot Exceed the User: If a viewer or sales_rep prompts an agent to "Approve quote #402 and issue a refund," the policy engine must reject the tool call because the underlying user lacks quote:approve and refund:issue.
2. The User Cannot Exceed the Agent's Purpose: Even if a workspace_owner chats with a "Customer Support Triage Agent," that agent is restricted to its declared tool scope (ticket:read, ticket:tag) and cannot execute workspace:delete or billing:export if manipulated by prompt injection.

Four Mandatory Controls for Agentic Execution

1. Server-Bound Identity Context (Never Trust LLM Parameters for Auth)

• Never pass userId, tenantId, or role as LLM-generated tool arguments!
• Bind { tenantId, delegatingUserId, agentId, runId, grantedScopes } inside the server-side execution context (On-Behalf-Of token / AgentExecutionContext) and inject it directly into the policy check inside every tool handler.

2. Action Classification & Human-in-the-Loop (HITL) Approval Gates

Classify every agent-callable tool into one of three risk tiers:

• Tier 1 — Read-Only (safe_read): Scoped by the user's and tenant's read permissions + field-level redaction (sensitive fields redacted before entering the LLM prompt context!).
• Tier 2 — Bounded Reversible Write (scoped_write): Allowed within explicit numeric/rate thresholds if both user and agent scopes permit (e.g., creating a draft quote or adding a task comment).
• Tier 3 — High-Impact / Irreversible / Financial / External Action (requires_approval): Sending external emails, approving quotes/orders, mutating production configs, deleting records, or charging money must halt and create a pending_approval request bound to the exact tool payload hash (payload_sha256), requiring human sign-off before execution.

3. Re-Verify Permissions When Resuming Paused Agent Runs

Agent runs that pause for minutes or hours (waiting for human approval, webhook callback, or retry) must re-evaluate the delegating user's active membership, role, and resource state immediately before executing the resumed step.

4. Distinct Agent Attribution in Audit Logs

Record both actor_agent_id (run_id) and on_behalf_of_user_id on every mutation and approval event so human actions and agent-executed actions are always distinguishable.