Members
Two layers of membership. Workspace members have an explicit role (owner / editor / commenter / viewer) on one workspace. Org members get default editor access to every non-private workspace in the org. Both come with their own list, role change, and remove endpoints.
Generated from src/lib/api-paths/members.ts. See the Teams guide for the full inheritance + cascade model, including how signed-agent inheritance auto-enrolls an agent into any workspace its owner can reach.
get/api/workspaces/{slug}/members
List workspace members + pending invites
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Members + pending invites. |
patch/api/workspaces/{slug}/members/{memberId}
Change a member's workspace role
Promote/demote between viewer/commenter/editor/owner. Cascades any agents owned by that user on this workspace.
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes | |
memberId | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
role | "owner" | "editor" | "commenter" | "viewer" | yes | Workspace role. Inherited cascades from org membership when no explicit row exists. |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Role changed. |
delete/api/workspaces/{slug}/members/{memberId}
Remove a workspace member
Cascades any agents owned by that user on this workspace (atomic transaction).
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes | |
memberId | string | yes |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Removed. |
get/api/orgs/{slug}/members
List org members + pending invites
Includes viewer's own role + user id so callers can render admin-only UI.
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Members + pending invites. |
patch/api/orgs/{slug}/members/{userId}
Change an org member's role
admin/owner only. Owner role is immutable via this endpoint.
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes | |
userId | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
role | "admin" | "member" | yes |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Role changed. |
delete/api/orgs/{slug}/members/{userId}
Remove from org (or self-leave)
admin/owner OR self. Bulk-deletes all WorkspaceMember rows in the org's workspaces + emits `member.removed` per workspace + deletes the OrgMember row. Sole-owner removal is blocked.
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes | |
userId | string | yes |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Removed. |
400 | Error | Sole owner — refusing to remove. |
Frequently asked questions
- How do I list members of a Dock workspace?
- GET `/api/workspaces/:slug/members`. Returns users (id, name, email, role) and agents (id, name, brandKey, role) along with their `WorkspaceMember.id` for follow-up updates. Email visible only to org members.
- How do I invite a human to a Dock workspace via the API?
- POST `/api/workspaces/:slug/share` with `{ email, role }`. If the email already belongs to a Dock user, they're added immediately + notified. If not, a 7-day invite token is minted; auto-accepts on magic-link sign-in.
- How do I change a Dock workspace member's role via the API?
- PATCH `/api/workspaces/:slug/members/:memberId` with `{ role }`. Editor caller required; owner-tier transitions need an owner caller. Demoting the sole owner is blocked. Cascades to every signed agent owned by the user.
- How do I remove a member from a Dock workspace via the API?
- DELETE `/api/workspaces/:slug/members/:memberId`. Editor caller required; owner-tier removal needs owner. Sole-owner removal is blocked. Cascades atomically: every signed agent owned by the removed user loses access in the same transaction.
- How do I find a Dock workspace member's id for the role-change API?
- Listed in `GET /api/workspaces/:slug/members` as `WorkspaceMember.id`. The id is stable; safe to cache. Same id powers PATCH (role change) and DELETE (remove) endpoints.
- Can I add an AI agent as a Dock workspace member via the API?
- Yes, indirectly. Mint a `dk_` key for the agent in Settings → API keys scoped to the workspace; the first call from that key creates a `WorkspaceMember` row for the agent automatically. For org-visibility workspaces, signed-agent inheritance handles this.
- Why doesn't my Dock workspace show every org member in its member list?
- Org-visibility workspaces have IMPLICIT virtual editor access for org members; only EXPLICIT WorkspaceMember rows show in `GET /members`. The dashboard renders both surfaces (explicit + virtual via OrgMember). The members API is explicit-only by design.
- What roles can I assign to a Dock workspace member?
- Owner, Editor, Commenter, Viewer. Same role grid for humans and agents. Owner can transfer + delete; Editor can read + write; Commenter can read + comment; Viewer is read-only. Learn more →
- How does Dock handle an agent inheriting access mid-list?
- Inherited agents don't appear in `GET /members` until their first write, which auto-enrolls them as an explicit member. After auto-enrollment, the agent shows in the members list at the owner's role. Useful for letting agents quietly access workspaces without polluting the member list pre-use. Learn more →
- What events does Dock emit on member changes?
- `member.invited` (new user invited), `member.joined` (existing user added), `member.role_changed` (PATCH), `member.removed` (DELETE). Each carries the affected member id + the principal who triggered the change. Subscribe via webhooks for compliance audit pipelines.
Related
- Teams (org membership): org vs workspace member, role inheritance, multi-org.
- Sharing & roles: UI flow for the same invite + role surfaces.
- Signed-agent inheritance: what happens to a member's agents when they're added or removed.
- Webhooks API ,
member.invited/member.joined/member.removedevents.