# Personal and organization workspaces

The authenticated actor is the caller represented by the validated access
token. The effective principal is the identity used for project membership.
They are the same in a personal workspace. Selecting an organization uses
its canonical principal for resource access while preserving the real actor.

All endpoints below use authenticated `POST` JSON. See
[authorization](https://m7.org/docs/api/api.mail.m7.org/authorization.md) for the exact Mailbox receiving audience.

## Inspect the caller

`POST /member/me` accepts `{}` and returns:

```json
{
  "status":1,"comment":"identity loaded",
  "data":{"member":{"username":"<user-name>","user_id":"<user-id>","principal_id":"<principal-uuid>"}}
}
```

`username` and `user_id` are `null` for callers whose kind is not `user`.
`principal_id` is the canonical service principal. This endpoint always
describes the real caller; an organization selection does not change it.

## Discover selectable organizations

`POST /orgs/list` accepts `{}` or optional JSON `orgs_dpop` for upstream
organization proof forwarding. It returns an organization snapshot, which
may reuse a valid cached result. `POST /orgs/refresh` accepts the same fields
and always obtains fresh disclosure. Both need the token's `orgs` scope and
verified disclosure for that caller and client.

Response `data` contains:

| Field | Meaning |
| --- | --- |
| `orgs` | Array of organizations with verified Management facts. |
| `verified_at`, `expires_at` | Unix seconds defining the snapshot's validity. |
| `cached` | Whether the list reused a cached snapshot. |
| `caller_principal_id` | Real authenticated caller's canonical principal UUID. |

Each organization has native `id`, canonical `principal_id`, `name`, `slug`,
`access_level` (`owner`, `admin`, or `member`), and `management_groups`.
Management entries include their `id`, `name`, caller `membership_id`, `role`,
`pub`, and capability `tags`. Use organization `id` for selection and
`principal_id` for canonical resource identity. These UUIDs are distinct;
names and slugs do not authorize access. The lists have no pagination input.

## Select an organization

For a business request, use one of:

```http
Org: <native-organization-uuid>
```

```json
{"org_id":"<native-organization-uuid>","project_id":"<project-uuid>"}
```

If both are present, they must match case-insensitively. IDs must be dashed,
non-nil UUIDs. To return to personal context, omit the header and field;
do not send `null` or an empty selection.

Selection requires current verified direct active Management membership.
Every organization-selected operation performs a fresh organization check,
including reads. A prior cached list, display name, token organization hint,
or membership in an unrelated group cannot replace that check. For machines,
the validated caller/client binding must identify the actual application.
Receiver credentials used for disclosure are service-owned, never accepted
from the request body.

`POST /workspace/context` with `{}` returns `workspace: "personal"`; with
an organization selection it returns `workspace: "organization"`. Its
response `data` also contains `principal` (the effective identity) and
`actor` (the real caller). Use each identity's `id`, `kind`, `rid`, and `name`
as needed for display; do not use returned details as authorization evidence
in later requests. The server rechecks authority.

Selected organization access does not by itself grant access to any project.
The organization must have project membership, and each action must be
allowed by both project capabilities and current organization grants.
Creation records the real caller as actor and makes the organization the
initial project Owner. Send attempts likewise preserve the actor while
recording the effective project principal as owner.

## Upstream proof and refresh failures

For `/orgs/list` and `/orgs/refresh`, provide any required upstream proof in
JSON `orgs_dpop`. For organization-selected business requests, use `Org-DPoP`
or `orgs_dpop`. The header takes precedence. This proof targets the SSO
organization request, independently of the Mailbox business request; see
[organization proof forwarding](https://m7.org/docs/api/api.mail.m7.org/authorization.md#organization-proof-forwarding).

Honor `DPoP-Nonce` challenges with a newly generated upstream proof. Expired
credentials, removed Management membership, denied disclosure, or unavailable
upstream verification cause an error. Refresh the selectable list after
authorization changes, and return the user to a valid selection instead of
retrying with stale organization facts.

[Return to Mailbox](https://m7.org/docs/api/api.mail.m7.org/README.md).