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 for the exact Mailbox receiving audience.

Inspect the caller

POST /member/me accepts {} and returns:

{
  "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:

Org: <native-organization-uuid>

{"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.

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.