---
title: "POST /v1/access-requests"
method: POST
path: "/v1/access-requests"
---

# POST /v1/access-requests

`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`

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.

## Request body

- AccessRequestCreate
  - `principalId` string: 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.
  - `mailboxId` string, required: From `listMailboxes`.
  - `capabilities` string[], required: From the engine's supported set. The founder may approve fewer.
  - `reason` string: 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 `200`

The request has succeeded.

- AccessRequestRecorded
  - `id` string, required
  - `principalId` string, required
  - `mailboxId` string, required
  - `capabilities` string[], required: What was ASKED for. The grant carries what was approved, which may be less.
  - `reason` string, nullable, required
  - `status` 'pending' | 'approved' | 'declined', required
  - `requestedAt` string, date-time, required
  - `decidedAt` string, date-time, nullable, required
  - `decidedBy` string, 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.

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/foundermail/apis/org.md) - [All operations](https://skmtc.dev/foundermail/apis/org/llms.txt) - [OpenAPI document](https://skmtc.dev/foundermail/apis/org/revisions/8bbb36e378ab?raw)