Architecture
Permissions and Trust
Delegated authority, scopes, approvals, and audit trails.
When an agent acts for someone, three parties need to trust the arrangement: the principal who delegates, the product being used, and the agent. This page describes how to make authority explicit.
Never share credentials
The most important rule: agents should never operate with a person's password or full session. A shared credential gives the agent every permission the person has, makes agent actions indistinguishable from human ones, and cannot be revoked without changing the password.
Use delegated authorization instead. OAuth 2.0 is the established standard here; the AX contribution is guidance on how to scope and present it.
OAuth 2.0 · IETF RFC 6749Scope around capabilities
Define scopes that match tasks people delegate, not your internal resource model:
| Avoid | Prefer |
|---|---|
admin | orders:read, returns:create |
write | cart:modify, orders:create |
full_access | Specific scopes, requested as needed |
Show scopes to people as outcomes: "Start returns for your orders" rather than returns:create.
Grants
A grant records who delegated what to which agent, for how long, and with which limits.
{
"grantId": "grt_41c",
"agent": { "id": "assistant.example", "name": "Example Assistant" },
"principal": "user_2291",
"scopes": ["orders:read", "cart:modify", "orders:create"],
"limits": {
"spend": { "perOrder": { "amount": 100, "currency": "EUR" }, "perDay": { "amount": 200, "currency": "EUR" } }
},
"approval": { "required": ["orders:create:above_limit", "payment_methods:modify"] },
"createdAt": "2026-10-06T13:00:00Z",
"expiresAt": "2026-10-13T13:00:00Z"
}List active grants in account settings with a one-click revoke. People should never have to wonder what an agent can do.
Approvals
For consequential actions, return approval_required and collect the decision through a channel you control, such as a push notification or an email link. Bind the approval to the exact parameters with a hash so the agent cannot change them afterward.
export async function requireApproval(action: string, params: unknown, ctx: Context) {
const hash = sha256(canonicalJson(params));
const existing = ctx.approvalId ? await approvals.get(ctx.approvalId) : null;
if (existing?.status === "approved" && existing.paramsHash === hash && !existing.used) {
await approvals.markUsed(existing.id);
return;
}
const approval = await approvals.create({ action, paramsHash: hash, grant: ctx.grant.id, ttlMinutes: 30 });
await notifyPrincipal(ctx.grant.principal, approval);
throw new ApprovalRequired(approval);
}Agent identity
Distinguish agent requests from human requests. At minimum, record the grant on every action. Where agents identify themselves (for example through the OAuth client or a signed header), record that too. Label agent activity in logs and notifications that people see.
Autonomy policy
Let people decide how much the agent can do alone. A simple, effective model has three modes per action:
| Mode | Behavior |
|---|---|
autonomous | Execute, record a receipt |
notify_after | Execute, then tell the principal |
approve_before | Pause for approval |
See Progressive Autonomy.
Related
Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.