Workspaces, projects, and use cases¶

Workspaces store references and collection rules that define a retrieval scope. The scope narrows what a caller can retrieve. It never grants access to source documents. IndentiaDB stores these resources through the /workspaces API on port 7001 when the workspace service is configured.

Resource hierarchy¶

Kind	Purpose	Access boundary
`workspace`	Collect document references, source rules, table references, and workspace scopes.	Expansion applies the caller's permissions.
`project`	Group workspace scopes and project-level configuration.	Referenced workspaces retain their own membership and document ACLs.
`use_case`	Combine 1 to 100 existing projects for a defined purpose.	Each project must be readable independently.

A use case has its own owner, writer, and reader assignments. Its hierarchy is fixed: use case, then project, then workspace. It cannot contain documents, tables, collection rules, or other use cases directly.

API reference¶

Method and path	Operation
`POST /workspaces`	Create a resource; the caller becomes its owner.
`GET /workspaces`	List caller-visible workspaces and projects.
`GET /workspaces?kind=use_case`	List caller-visible use cases explicitly.
`GET /workspaces/{id}`	Read resource metadata and the caller's role.
`PATCH /workspaces/{id}`	Update metadata; a use case can atomically replace its `projects` array.
`PUT /workspaces/{id}/members`	Replace membership roles; owner only.
`POST /workspaces/{id}/members/me`	Add the owner's verified user SID as an owner member; idempotent.
`POST /workspaces/{id}/expand`	Expand a scope under the caller's permissions.
`DELETE /workspaces/{id}`	Delete the resource; owner only.

Create a use case with kind: "use_case", a name, and a projects array of unique project IRIs in the configured storage tenant. Names contain 1 to 200 characters; descriptions contain at most 4,000. Kind is immutable. Item-add and item-remove endpoints do not apply to use cases.

The server rechecks project existence and access in the authoritative write. It refuses project deletion with 409 while a use case references that project. Deleting a use case does not delete its projects or source documents.

Expand scopes without widening access¶

/expand returns iris, uploadIris, tables, and collections. Collections are rules for the consumer to apply as filters; they are not a precomputed list of every matching document. IRI expansion accepts a limit of 1 to 5,000 and a cursor for subsequent pages.

Expansion checks access at every project and workspace edge, unions allowed scopes, and removes duplicates. Document-level security still applies when the consumer reads documents. Sharing a use case does not share its linked projects.

A use case's detail response includes all linked project IRIs, but expansion omits projects the caller cannot read. An application that requires the complete use case must check access to every linked project before presenting results.

Metadata and project replacement use last-writer-wins semantics. They do not provide revision checks or compare-and-set. Reload before editing and refresh after writes; concurrent updates can replace each other's changes.

Membership and consistency¶

New OIDC-created workspaces record the creator's owner identity and verified user SID. Older resources may need the owner to add their SID with POST /workspaces/{id}/members/me. A group SID and a raw directory SID remain different principals; the server does not convert them into equivalent grants.

The workspace-reader role enables a roster-only read for an explicitly configured service token in its own tenant. It grants no document scope, item expansion, or write access. It cannot be combined with sid-delegator.

Cluster reads establish a linearizable Raft read point before checking membership. Failure to confirm it within two seconds returns 503 workspace_consistency_unavailable, rather than an outdated membership decision. Standalone reads do not need a Raft barrier.

Project MCP bindings reference registry server UUIDs and enabled servers. They select project configuration; they do not grant permission to invoke a tool or replace the registry's own authorization.