# Caller and organization workspace context

Use these routes to identify the current receiving principal and select an
organization workspace. An organization-owned bucket combines live organization Management grants with the organization principal's bucket membership.

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

1. Obtain an admitted token with `orgs`, then call `/v1/orgs/list`.
2. Pick an organization ID from `data.orgs`; do not construct or trust facts
   supplied by UI input.
3. Send `Org: ORG_UUID` or JSON `org_id` on context and supported resource
   requests. When both are present, they must match case-insensitively.
4. 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.

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

Organization selection applies to bucket, conversion, document and job routes.
For processing and job operations, include both `org_id` (or `Org`) and the
required `bucket_id`. The response preserves the real actor while operations
use the organization's receiving principal. [Bucket context](https://m7.org/docs/api/api.document.m7.org/buckets.md)
reports the intersected capability list. Explicit Management tag selections
replace defaults; verified empty selections use owner/admin defaults, while
Member has no automatic grant. Arbitrary tag data or organization visibility
does not create a bucket membership.

## Capability definitions

`GET /v1/capabilities.json` is unauthenticated and returns the raw public
definition document, without the ordinary `status`/`data` envelope. Only `GET` is 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](https://m7.org/docs/api/api.document.m7.org/authorization.md) for the service's complete credential
and error contract. For upstream proof and disclosure rules, see
[SSO organization projection](https://m7.org/docs/api/sso.user.m7.org/userinfo-orgs.md).