Skip to main content

​
Members, Invitations, and Ownership

These routes manage workspace team access.

​
Endpoints

  • GET /api/workspaces/:workspaceId/members
  • POST /api/workspaces/:workspaceId/members/invite
  • PATCH /api/workspaces/:workspaceId/members/:memberId
  • DELETE /api/workspaces/:workspaceId/members/:memberId
  • POST /api/workspaces/:workspaceId/transfer-ownership
  • GET /api/workspaces/invitations/pending
  • POST /api/workspaces/invitations/:token/accept
  • DELETE /api/workspaces/invitations/:invitationId

​
Auth and permission model

All routes are session-only and reject API-key auth.
  • members:read: list members
  • members:invite: invite members
  • members:update_roles: change member role
  • members:remove: remove member
  • owner role: transfer ownership

​
Invite request payload

POST /api/workspaces/:workspaceId/members/invite 
{
  "email": "user@example.com",
  "role": "viewer"
}
Batch invite is also supported: 
{
  "emails": ["a@example.com", "b@example.com"],
  "role": "editor"
}
Rules enforced by the API:
  • Up to 10 emails per request.
  • Role must be admin, editor, or viewer.
  • Role escalation is blocked if actor cannot manage target role.
  • Team-member plan limits include active members plus pending invites.
  • Invitations expire after 7 days.

​
Role updates and removals

PATCH /api/workspaces/:workspaceId/members/:memberId 
{ "role": "admin" }
Safeguards:
  • Self role-change is blocked.
  • Non-owner users cannot modify owner role.
  • Last-owner demotion is blocked.
DELETE /api/workspaces/:workspaceId/members/:memberId Safeguards:
  • Owner removal is blocked.
  • Equal/higher-role removal is blocked unless valid by policy.
  • Removal also deletes that user’s workspace API keys and clears workspace session cache.

​
Ownership transfer

POST /api/workspaces/:workspaceId/transfer-ownership 
{ "newOwnerId": "usr_123" }
Rules:
  • Caller must be current owner.
  • Target must be an active member of the same workspace.
  • Transfer to self is blocked.
  • Previous owner is downgraded to admin.

​
Invitation lifecycle routes

  • GET /api/workspaces/invitations/pending: lists pending invites for current user email.
  • POST /api/workspaces/invitations/:token/accept: accepts a tokenized invite.
  • DELETE /api/workspaces/invitations/:invitationId: recipient can decline, inviter can cancel.
Accept endpoint safeguards:
  • Token is hashed before lookup.
  • Invalid/expired/wrong-email tokens return a generic invalid response.
  • Workspace join cap is enforced at acceptance time.

​
Common errors

  • 400: invalid role, invalid invite payload, transfer precondition failed
  • 403: missing permission, role escalation, owner protections
  • 404: workspace/member/invitation not found
  • 409: invite/member lifecycle conflict (already invited/member)