# Caller and organization workspace context

Use these routes to identify the current receiving principal and select an
organization workspace. Organization selection is supported only on the integrated bucket workflows listed below.

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

Caller/workspace tools accept validated tokens from either directory mode;
bucket resource routes still require consumer mode, with the documented upload
exception. Organization acquisition keeps its canonical SSO subject restrictions.

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.bigfs.m7.org/v1/workspace/context \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"org_id":"ORG_UUID"}'
```

## Supported selected-organization operations

| Route family | Supported routes | Required additional authority |
| --- | --- | --- |
| Bucket | `context`, `search`, `view`, `delete`, all `access/*`, `vault/search` | Current bucket Management membership and the exact action, except context bootstrapping. Creation requires an admitted user or authorized organization. |
| Key | `/v1/key/search` | Selected parent bucket membership plus `key.list`. |
| Upload | `/v1/upload/form_data`, `/v1/upload/post_data` | Target bucket owner/admin plus `upload.store`. Keep the token/proof and `Org` headers with multipart or raw uploads. |
| Asset | `/v1/asset/search`, `/v1/asset/delete` | Parent bucket membership plus `asset.list` or `asset.delete`; deletion still requires owner/admin. |
| Download | `/v1/download/pull` | Parent bucket membership plus `download.pull`. |
| Task queue | `/v1/task_queue/search`, `/v1/task_queue/process` | Authorized buckets and `task_queue.list` or `task_queue.process`; processing still requires owner/admin. |

Select an organization on another resource operation and the service returns
`403`. Vault workflows remain under personal authority. Keep selection explicit
and avoid reusing an organization's IDs after switching to personal context.

Effective actions are the intersection of the live organization's Management
tag selections, current catalogue and resource membership profile/role ceiling.
Verified empty selections allow owner/admin defaults; Member has no automatic
grant. Explicit selections replace defaults, unknown selections grant nothing,
and `readonly` is additive rather than a deny for separately selected writes.
The organization's role does not confer service Root or resource Owner.
Use [bucket context](https://m7.org/docs/api/api.bigfs.m7.org/buckets.md#inspect-current-access) for the actual result.

The older [organization endpoint/search integration](https://m7.org/docs/api/api.bigfs.m7.org/organizations.md)
returns the full live caller projection, including owned-app inventories.
It remains distinct from the cached selector snapshot and identity-only import
boundary described there.

## 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](https://m7.org/docs/api/api.bigfs.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).