# 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"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.transactionlink.io/docs/transactionlink-api/api-reference/organization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.