---
title: "GET /v1/me"
method: GET
path: "/v1/me"
---

# GET /v1/me

`GET /v1/me`

## Request

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

The session's own reach: the caller's principal, and every granted mailbox with the addresses routing into it.

## Response `200`

The request has succeeded.

- Me: ⛔ **The MAIL policy, and it is deliberately not the estate's.** The estate a session operates on here — and that `/authorize` stamps into a MAIL token — is the oldest membership whose principal holds a ready grant, falling back to the oldest membership. One stated policy for `/me` and `/authorize` both. ⚠️ `setActiveOrg` does NOT steer this. The org selector moves which organisation the CONSOLE administers; a token for mail has to land on the organisation that actually has mail in it, and a founder who switched to an estate they hold no grant in would otherwise lose their inbox by changing an admin screen. See `resolve-session-grant.ts`.
  - `principal` MePrincipal, required: The session user's own principal — the human behind the cookie, never an agent.
    - `id` string, required
    - `kind` 'human', required: Always `human` here: `Principal.kind`'s vocabulary, narrowed to what a session can be.
    - `name` string, required: What the org calls this person. Display only.
  - `mailboxes` MeMailbox[], required: The READY granted set: every granted mailbox whose engine container has settled. Empty — never an error — for a principal holding no grant, or none whose mailbox is ready.
    - `id` string, required: The ENGINE mailbox id — the identity the token's `mailboxIds` carry and the Mailbox surface's paths take (`/v1/mailboxes/{id}/…`), so the client aims its reads without a join. Only settled mailboxes appear here, which is why it is never null.
    - `label` string, required: The org-scoped display label.
    - `handles` string[], required: Every address routing into this mailbox — what the world writes to, and what a send may go out as. A `+tag` of any of them routes here too. `*@domain` is the domain's catch-all: the mailbox receives, and may send as, any address on that domain nobody else has claimed — but `*@domain` itself is never an address to send from.
  - `accessWithdrawn` boolean, required: Whether the organisation this session's mail resolves to has its access withdrawn. When it has, `mailboxes` is empty because nothing in that organisation can be opened until an owner or admin restores access from billing — NOT because nothing is granted — and `/authorize` answers 402. ⛔ The two empties must be told apart by this read. A client that only had the list told a withdrawn founder "nobody has given you a mailbox" (driven live 2026-10-19): the walk skips a withdrawn organisation, so the list is empty either way, and a cold load never asks the token endpoint the question whose 402 would have said so.

## 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)