Files
kandev/docs/plans/team-access/task-04-management-api.md
T
João Salavisa 481359ddb2 feat(auth): organization units, tenancy, roles and scopes for team access (#2919)
Co-authored-by: Kandev Agent <agent@kandev.dev>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-05 13:40:43 +00:00

66 lines
2.7 KiB
Markdown

---
id: "04-management-api"
title: "Management API, roles, and user directory"
status: todo
wave: 2
depends_on: ["03-reach-and-scope-resolution"]
plan: "plan.md"
spec: "../../specs/workspaces/requirements/org-units.md"
---
# Task 04: Management API, Roles, and User Directory
## Acceptance
- `PATCH /api/v1/workspaces/{id}` accepts `visibility`, gated on
`workspace.manage`.
- `POST /api/v1/workspaces/visibility/bulk` sets visibility across the caller's
own workspaces, for the one-time opt-in.
- `PATCH /api/v1/orgs/current/settings` accepts `default_workspace_visibility`,
gated on `org.settings.manage`.
- `GET/PUT/DELETE /api/v1/workspaces/{id}/members[/{userId}]` list, add-or-
re-role, and remove, gated on `workspace.read` / `member.manage`. `PUT` is
idempotent and carries the workspace role.
- `POST /api/v1/workspaces/{id}/transfer-ownership` moves the accountable
owner, demotes the previous owner to `collaborator`, and updates
`workspaces.owner_id` in the same transaction. A target with no row is
refused.
- Removing the last `owner` row, or the row matching `owner_id`, is refused with
a distinct code.
- Setting `visibility = 'org'` on a workspace owned by a `guest` is refused.
- Adding a nonexistent, disabled, or already-present user returns 400 with a
distinct code per case and writes nothing.
- `PATCH /api/v1/users/{id}` accepts the four org roles, gated on
`org.members.manage`, with the last-owner and self-change guards.
- `GET /api/v1/users/directory` returns **only** id and display name for active
users. A pinning test over the response field set fails if email, role, or
status is ever added.
- Workspace DTOs carry `visibility`, `member_count`, `viewer_role`, and
`scopes`; `GET /api/v1/auth/me` carries `org_scopes`.
## Verification
- `go test ./internal/task/... ./internal/user/... ./internal/auth/... -run 'TestVisibility|TestMember|TestTransferOwnership|TestUserDirectory|TestRoleChange'`
- `go test ./internal/user/... -run TestUserDirectoryFieldSet`
## Files Likely Touched
- `apps/backend/internal/task/handlers/workspace_handlers.go`
- `apps/backend/internal/task/service/service_members.go`
- `apps/backend/internal/task/dto/dto.go`
- `apps/backend/internal/user/handlers/handlers.go`, `internal/user/dto/dto.go`
- `apps/backend/internal/auth/httpapi/handlers.go`
## Inputs
- Spec: API surface, Permissions, Failure modes; `roles-and-scopes.md`
Permissions.
- Patterns: existing workspace handler shapes; the no-existence-leak rule for
anything reachable cross-user.
## Output Contract
Report the error-code matrix, the directory field pinning test and the mutation
proving it fails, RED/GREEN commands, and set this task plus its plan checkbox
to done.