Caller and organization workspace context

Use these routes to identify the current receiving principal and select an organization workspace. Project and drop workflows remain personal; organization selection is available for workspace context only.

Routes

Send a Bearer access token with JSON requests. These routes use POST and return Cache-Control: private, no-store.

Route	Input	Success `data`
`/v1/member/me`	`{}`	`member.username`, `member.user_id`, `member.principal_id`. User fields are `null` for an application.
`/v1/orgs/list`	Optional `orgs_dpop`	Organization snapshot, using a bounded caller/receiver-bound read cache when available.
`/v1/orgs/refresh`	Optional `orgs_dpop`	A fresh snapshot; removed organizations are removed from the selector.
`/v1/workspace/context`	Optional `org_id`, `orgs_dpop`, or corresponding headers	`workspace` (`personal` or `organization`), selected `principal`, and authenticated `actor`.

The member principal ID is the canonical receiving UUID, distinct from a user ID or an application's public client ID. Org selection never changes the actor. Snapshots contain orgs, Unix-second verified_at and expires_at, Boolean cached, and caller_principal_id. Each org contains id, principal_id, name, slug, access_level, and direct management_groups with membership IDs, roles, pub, and tag facts. The selector snapshot omits owned-app inventories; it is not an import grant or durable permission record.

Acquire and select an organization

Organization acquisition requires a canonical consumer SSO user or ordinary application token, explicitly granted orgs scope, and recipient-authenticated disclosure under the owner's current policy. Ordinary applications can be registered in either directory; tenant-member and personal-owner-proxy tokens cannot acquire an organization workspace. Application ownership does not establish Management membership. A filtered empty success means no visible organization; a failed lookup must remain an error.

Obtain an admitted token with orgs, then call /v1/orgs/list.
Pick an organization ID from data.orgs; do not construct or trust facts supplied by UI input.
Send Org: ORG_UUID or JSON org_id on context and supported resource requests. When both are present, they must match case-insensitively.
Keep the selection with subsequent requests and reload it after admission, membership, capability or session changes.

org_id must be a non-nil dashed UUID. Organization display names are not authority. On supported selected resource operations, the service reacquires live SSO facts for both reads and writes; a saved selector is only UI state.

When the token is bound, orgs_dpop on list/refresh carries the caller's proof for the trusted SSO organizations endpoint. On context/resource requests use Org-DPoP or JSON orgs_dpop (the header wins). It must be a string of at most 8192 bytes without line breaks or commas. Resolve the trusted SSO endpoint through its discovery contract before creating the proof, bind it to SSO's POST request and token, and do not confuse it with an API-bound DPoP header. An upstream challenge is forwarded as DPoP-Nonce; generate a fresh proof and retry once only while the token/session/selection is unchanged. Do not cache proofs or loop automatically.

curl -sS https://api.drop.service.m7.org/v1/workspace/context \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"org_id":"ORG_UUID"}'

Projects and project drops currently reject organization selection with HTTP 400, including organization proof headers. Do not send Org, Org-DPoP, org_id, org_name, or orgs_dpop to those workflows. Their capability context comes from project Management membership.

Capability definitions

GET /v1/capabilities.json is unauthenticated and returns the raw public definition document, without the ordinary status/data envelope. HEAD is also registered. Optional positive integer catalogue_version selects a retained revision; omission selects the current imported catalogue. The document identifies the service and revision, primitive actions, family metadata, presets/bundles and role-default mappings. It describes possible actions, not the caller's granted actions. Use resource context for effective authority. A missing revision can return 404; unavailable or invalid definitions can return 503.

Failures

Missing or invalid caller credentials return 401; denied receiving admission or resource authority returns 403; malformed/conflicting selection returns 400. Receiver configuration or ACL availability failures return 503. An org-scope/disclosure/proof failure does not fall back to personal access. Use Authorization for the service's complete credential and error contract. For upstream proof and disclosure rules, see SSO organization projection.