> 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/organization.md).

# Organization

The Organization API allows businesses to programmatically manage their organisational structure by retrieving available roles and listing workspaces — both live and sandbox environments

## List available roles in organization

> Returns all available roles for the organization (\`owner\`, \`admin\`, \`member\`). Requires \`can\_manage\_users\` 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":{"OrganizationRoleResponse":{"title":"OrganizationRoleResponse","required":["id","name","organizationId"],"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the role"},"name":{"type":"string","description":"Name of the role (e.g. `owner`, `admin`, `member`)"},"organizationId":{"type":"string","format":"uuid","description":"Identifier of the organization this role belongs to"}}},"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/roles":{"get":{"tags":["Organization Roles"],"summary":"List available roles in organization","description":"Returns all available roles for the organization (`owner`, `admin`, `member`). Requires `can_manage_users` permission.","operationId":"list-organization-roles","parameters":[{"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/OrganizationRoleResponse"}}}}},"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"}}}},"500":{"description":"Internal Server Error – unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## List workspaces for the organization

> Returns all workspaces belonging to the organization. Filters results to workspaces the token has \`can\_view\_workspace\` permission on.

```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":{"PublicWorkspaceResponse":{"title":"PublicWorkspaceResponse","required":["id","name","workspaceType"],"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the workspace"},"name":{"type":"string","description":"Name of the workspace"},"description":{"type":"string","nullable":true,"description":"Description of the workspace"},"workspaceType":{"type":"string","description":"Type of the workspace (`LIVE`)","enum":["LIVE"]}}},"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":{"get":{"tags":["Workspaces"],"summary":"List workspaces for the organization","description":"Returns all workspaces belonging to the organization. Filters results to workspaces the token has `can_view_workspace` permission on.","operationId":"list-organization-workspaces","parameters":[{"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/PublicWorkspaceResponse"}}}}},"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"}}}},"500":{"description":"Internal Server Error – unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## List available roles for a workspace

> List all available roles 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":{"WorkspaceRoleResponse":{"title":"WorkspaceRoleResponse","required":["id","name","workspaceId","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"},"description":{"type":"string","nullable":true,"description":"Description of the role"},"permissions":{"type":"array","nullable":true,"description":"Permissions granted by this role","items":{"$ref":"#/components/schemas/PermissionResponse"}},"createdDateTime":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the role was created"},"type":{"type":"string","description":"Type of the role (CUSTOM or BASE)"}}},"PermissionResponse":{"title":"PermissionResponse","required":["id","resourceType","relation"],"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the permission"},"resourceType":{"type":"string","description":"Type of resource this permission applies to (e.g. table, workspace)"},"relation":{"type":"string","description":"Relation/action this permission grants (e.g. can_edit_data)"},"resourceId":{"type":"string","format":"uuid","nullable":true,"description":"Identifier of the specific resource (null means all resources of this type)"}}},"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}/roles":{"get":{"tags":["Workspace Roles"],"summary":"List available roles for a workspace","description":"List all available roles for a workspace. Requires `can_view_workspace` permission.","operationId":"list-workspace-roles","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/WorkspaceRoleResponse"}}}}},"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"}}}}}}}}}
```