Control agent access

Mailbox grants define what a subject may do. Token scopes can narrow those grants but cannot widen them.

Mailbox roles

Role	Intended use	Main capabilities
reader	Read-only agent or auditor	Read and monitor mail; observe visible requests
operator	Normal agent	Reader capabilities, drafts, intent requests, cancellation, and request listing
approver	Human or tightly controlled policy agent	Read requests and approve or deny them
owner	Mailbox administrator	Every mailbox tool, including direct actions and send

Use extra_scopes for exceptions rather than granting a broader role.

Grants and token scopes

Suppose an agent has operator on Support and reader on Billing. A token scoped to grp:read@* can read both but cannot create an approval request on either. Adding wants_to_move@<support mailbox> to the token enables only that intent on Support, because both the grant and token must match.

An empty token scope list means “do not narrow.” It does not mean “no access.”

Sensitive grants

Granting an agent direct move/copy/file actions, send_draft, or approval_commit requires an organization admin, an explicit confirmation in the write request, and an already configured mailbox. Giving approval_commit to an agent also requires bot-commit policy at both organization and mailbox level.

These confirmations apply to one request and are audited; they are not durable settings that make future grants silent.

Revoke safely

• Revoke or edit a mailbox grant to reduce every existing token’s effective permission.
• Disable a token for a reversible stop.
• Revoke a token for a terminal stop.
• Disable or delete an agent to reject all of its tokens.
• Disconnect an OAuth application to revoke its consent, tokens, generated grants, and associated agent together.

Alcarta returns 404 for a mailbox the subject has no grant on, even if it exists in the same organization. Do not interpret that response as evidence that an administrator mistyped the ID.