> For the complete documentation index, see [llms.txt](https://docs.transactionlink.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.transactionlink.io/docs/transactionlink-api/api-reference/workspace-memberships.md).

# Workspace memberships

The Workspace Memberships API gives businesses full visibility into who has access to each workspace, including both directly assigned members and inherited access from organization admins.

## List workspace memberships

> List all memberships for a workspace. Requires \`can\_view\_workspace\` permission.

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"}],"security":[{"organizationToken":[]}],"components":{"securitySchemes":{"organizationToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Organization API token (tot_) — preferred authentication method. Pass the token directly without Bearer prefix."}},"schemas":{"WorkspaceMembershipResponse":{"title":"WorkspaceMembershipResponse","required":["workspaceId","userId","role"],"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid","description":"Identifier of the workspace"},"userId":{"type":"string","format":"uuid","description":"Identifier of the user"},"role":{"$ref":"#/components/schemas/RoleRefResponse","description":"Role assigned to the user in this workspace"}}},"RoleRefResponse":{"title":"RoleRefResponse","required":["id","name","workspaceId","createdDateTime","type"],"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the role"},"name":{"type":"string","description":"Name of the role"},"workspaceId":{"type":"string","format":"uuid","description":"Identifier of the workspace this role belongs to"},"createdDateTime":{"type":"string","format":"date-time","description":"Timestamp when the role was created"},"type":{"type":"string","description":"Type of the role (e.g. WORKSPACE)"}}},"ErrorResponse":{"required":["errors","fingerprint"],"type":"object","properties":{"fingerprint":{"type":"string","description":"Unique identifier for this error instance"},"errors":{"type":"array","description":"List of error details","items":{"required":["code","message"],"properties":{"code":{"type":"string","description":"Error code representing the type of error"},"message":{"type":"string","description":"Error message providing more details about the error"}}}}}}}},"paths":{"/workspaces/{workspaceId}/memberships":{"get":{"tags":["Workspace Memberships"],"summary":"List workspace memberships","description":"List all memberships for a workspace. Requires `can_view_workspace` permission.","operationId":"list-workspace-memberships","parameters":[{"name":"workspaceId","in":"path","description":"Identifier of the workspace","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"Organization token (`tot_`). Pass the token directly without Bearer prefix.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"200","headers":{"Content-Type":{"description":"Content type of the response","style":"simple","explode":false,"schema":{"type":"string"}}},"content":{"application/json;charset=UTF-8":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceMembershipResponse"}}}}},"400":{"description":"Bad Request – invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – JWT token missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error – unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## List workspace memberships including organization admins

> List all direct and inherited (organization admin) memberships for a workspace. Requires \`can\_view\_workspace\` permission.

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"}],"security":[{"organizationToken":[]}],"components":{"securitySchemes":{"organizationToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Organization API token (tot_) — preferred authentication method. Pass the token directly without Bearer prefix."}},"schemas":{"MembershipsResponse":{"title":"MembershipsResponse","required":["directMemberships","inheritedMemberships"],"type":"object","properties":{"directMemberships":{"type":"array","description":"Direct workspace memberships","items":{"$ref":"#/components/schemas/WorkspaceMembershipResponse"}},"inheritedMemberships":{"type":"array","description":"Inherited memberships from organization admins","items":{"$ref":"#/components/schemas/InheritedMembershipResponse"}}}},"WorkspaceMembershipResponse":{"title":"WorkspaceMembershipResponse","required":["workspaceId","userId","role"],"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid","description":"Identifier of the workspace"},"userId":{"type":"string","format":"uuid","description":"Identifier of the user"},"role":{"$ref":"#/components/schemas/RoleRefResponse","description":"Role assigned to the user in this workspace"}}},"RoleRefResponse":{"title":"RoleRefResponse","required":["id","name","workspaceId","createdDateTime","type"],"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the role"},"name":{"type":"string","description":"Name of the role"},"workspaceId":{"type":"string","format":"uuid","description":"Identifier of the workspace this role belongs to"},"createdDateTime":{"type":"string","format":"date-time","description":"Timestamp when the role was created"},"type":{"type":"string","description":"Type of the role (e.g. WORKSPACE)"}}},"InheritedMembershipResponse":{"title":"InheritedMembershipResponse","required":["organizationId","userId","roleId","status"],"type":"object","properties":{"organizationId":{"type":"string","format":"uuid","description":"Identifier of the organization"},"userId":{"type":"string","format":"uuid","description":"Identifier of the user"},"roleId":{"type":"string","format":"uuid","description":"Identifier of the role"},"status":{"type":"string","description":"Status of the user in the organization (e.g. ACTIVE)"}}},"ErrorResponse":{"required":["errors","fingerprint"],"type":"object","properties":{"fingerprint":{"type":"string","description":"Unique identifier for this error instance"},"errors":{"type":"array","description":"List of error details","items":{"required":["code","message"],"properties":{"code":{"type":"string","description":"Error code representing the type of error"},"message":{"type":"string","description":"Error message providing more details about the error"}}}}}}}},"paths":{"/organizations/workspaces/{workspaceId}/memberships":{"get":{"tags":["Workspace Memberships"],"summary":"List workspace memberships including organization admins","description":"List all direct and inherited (organization admin) memberships for a workspace. Requires `can_view_workspace` permission.","operationId":"list-workspace-memberships-with-organization","parameters":[{"name":"workspaceId","in":"path","description":"Identifier of the workspace","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"Organization token (`tot_`). Pass the token directly without Bearer prefix.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"200","headers":{"Content-Type":{"description":"Content type of the response","style":"simple","explode":false,"schema":{"type":"string"}}},"content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/MembershipsResponse"}}}},"400":{"description":"Bad Request – invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – JWT token missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error – unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Remove workspace membership

> Remove a user's membership from a workspace. Requires \`can\_manage\_workspace\_access\` permission on the workspace.

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"}],"security":[{"organizationToken":[]}],"components":{"securitySchemes":{"organizationToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Organization API token (tot_) — preferred authentication method. Pass the token directly without Bearer prefix."}},"schemas":{"ErrorResponse":{"required":["errors","fingerprint"],"type":"object","properties":{"fingerprint":{"type":"string","description":"Unique identifier for this error instance"},"errors":{"type":"array","description":"List of error details","items":{"required":["code","message"],"properties":{"code":{"type":"string","description":"Error code representing the type of error"},"message":{"type":"string","description":"Error message providing more details about the error"}}}}}}}},"paths":{"/workspaces/{workspaceId}/memberships/{userId}":{"delete":{"tags":["Workspace Memberships"],"summary":"Remove workspace membership","description":"Remove a user's membership from a workspace. Requires `can_manage_workspace_access` permission on the workspace.","operationId":"delete-workspace-membership","parameters":[{"name":"workspaceId","in":"path","description":"Identifier of the workspace","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}},{"name":"userId","in":"path","description":"Identifier of the user to remove","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"Organization token (`tot_`). Pass the token directly without Bearer prefix.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"200"},"400":{"description":"Bad Request – invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – JWT token missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error – unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Add or update workspace membership

> Add or update workspace membership for a user. Requires \`can\_manage\_workspace\_access\` permission on the workspace.

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"}],"security":[{"organizationToken":[]}],"components":{"securitySchemes":{"organizationToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Organization API token (tot_) — preferred authentication method. Pass the token directly without Bearer prefix."}},"schemas":{"CreateMembershipRequest":{"title":"CreateMembershipRequest","required":["userId","roleId"],"type":"object","properties":{"userId":{"type":"string","format":"uuid","description":"Identifier of the user to add to the workspace"},"roleId":{"type":"string","format":"uuid","description":"Identifier of the role to assign to the user"}}},"WorkspaceMembershipResponse":{"title":"WorkspaceMembershipResponse","required":["workspaceId","userId","role"],"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid","description":"Identifier of the workspace"},"userId":{"type":"string","format":"uuid","description":"Identifier of the user"},"role":{"$ref":"#/components/schemas/RoleRefResponse","description":"Role assigned to the user in this workspace"}}},"RoleRefResponse":{"title":"RoleRefResponse","required":["id","name","workspaceId","createdDateTime","type"],"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the role"},"name":{"type":"string","description":"Name of the role"},"workspaceId":{"type":"string","format":"uuid","description":"Identifier of the workspace this role belongs to"},"createdDateTime":{"type":"string","format":"date-time","description":"Timestamp when the role was created"},"type":{"type":"string","description":"Type of the role (e.g. WORKSPACE)"}}},"ErrorResponse":{"required":["errors","fingerprint"],"type":"object","properties":{"fingerprint":{"type":"string","description":"Unique identifier for this error instance"},"errors":{"type":"array","description":"List of error details","items":{"required":["code","message"],"properties":{"code":{"type":"string","description":"Error code representing the type of error"},"message":{"type":"string","description":"Error message providing more details about the error"}}}}}}}},"paths":{"/workspaces/{workspaceId}/memberships/{userId}":{"put":{"tags":["Workspace Memberships"],"summary":"Add or update workspace membership","description":"Add or update workspace membership for a user. Requires `can_manage_workspace_access` permission on the workspace.","operationId":"create-workspace-membership","parameters":[{"name":"workspaceId","in":"path","description":"Identifier of the workspace","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}},{"name":"userId","in":"path","description":"Identifier of the user","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"Organization token (`tot_`). Pass the token directly without Bearer prefix.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMembershipRequest"}}},"required":true},"responses":{"200":{"description":"200","headers":{"Content-Type":{"description":"Content type of the response","style":"simple","explode":false,"schema":{"type":"string"}}},"content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/WorkspaceMembershipResponse"}}}},"400":{"description":"Bad Request – invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – JWT token missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error – unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```