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.

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 for the actual result.

The older organization endpoint/search integration 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 for the service's complete credential and error contract. For upstream proof and disclosure rules, see SSO organization projection.