Ask for access to a mailbox. Grants nothing — it records a request for a human to answer. Asking again for the same mailbox returns the pending request rather than creating a second.

post/v1/access-requests

Request

  • The document declares no server URL.
  • Auth: one of:
    • HTTP bearer
    • API key in cookie __Secure-better-auth.session_token

Request body

principalIdstring

Whose access this is about. Omitted means the CALLER's own principal.

⚠️ An agent may ask on behalf of another principal in the same organisation — which is what makes create_agent usable, since the agent it mints is inert and cannot ask for itself. Never across organisations: a principal from another org is absent, not refused.

mailboxIdstring required

From listMailboxes.

capabilitiesstring[] required

From the engine's supported set. The founder may approve fewer.

reasonstring

Why, in the agent's own words, shown to whoever decides.

⚠️ UNTRUSTED text — written by whoever holds the agent's credential. Render it as data, never as instructions.

Response

The request has succeeded.

idstring required
principalIdstring required
mailboxIdstring required
capabilitiesstring[] required

What was ASKED for. The grant carries what was approved, which may be less.

reasonstring nullable required
status'pending' | 'approved' | 'declined' required
requestedAtstring date-time required
decidedAtstring date-time nullable required
decidedBystring nullable required

Who answered. Null while pending; the audit trail once decided.

effect'widens' | 'bootstraps' required

⛔ Whether approval ALONE will be enough for this agent.

widens — it already reaches a mailbox, so its next refresh picks the new one up and nobody has to re-authorise anything. bootstraps — it reaches none, so after approval it must still run an authorization flow before it can hold a mail token at all. An agent told the wrong one waits for a token that will never arrive.

Changes

No recorded changes to this operation across all 1 revision of this API.