# Collaborator groups
Use the following endpoints to manage your collaborator groups.
# Rate limits
The collaborator groups resource has the following rate limit:
Type | Resource | Limit |
---|---|---|
All | All Collaborator groups endpoints | 60 requests per minute |
# Quick reference
Type | Resource | Description |
---|---|---|
GET | /api/user_groups | List collaborator groups. |
GET | /api/user_groups/:id | Get collaborator group details. |
POST | /api/user_groups | Create a collaborator group. |
PUT | /api/user_groups/:id | Update a collaborator group. |
DELETE | /api/user_groups/:id | Delete a collaborator group. |
GET | /api/user_groups/:id/members | List collaborator group members. |
POST | /api/user_groups/:id/members | Add members to a collaborator group. |
DELETE | /api/user_groups/:id/members | Remove members from a collaborator group. |
GET | /api/user_groups/:id/project_grants | List a collaborator group's project grants. |
# List collaborator groups
Retrieves a list of collaborator groups from a workspace.
GET /api/user_groups
# Query parameters
Name | Type | Description |
---|---|---|
name | string optional | Filter collaborator groups by their name. |
page[number] | integer optional | The page number to retrieve. The default value is 1 . |
page[size] | integer optional | The number of items per page to retrieve. The default and maximum value is 100 . |
# Sample request
curl -X GET 'https://www.workato.com/api/user_groups?page[number]=1&page[size]=100' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"data": [
{
"id": "am-WxEKCibh-dTXBtz",
"name" : "All collaborators",
"description": null,
"members_count": 5,
"system": true,
"created_at": "2024-08-01T13:35:11.691-07:00",
"updated_at": "2024-08-01T13:35:11.691-07:00"
},
{
"id": "pf-APHDLgAD-cTXBtz",
"name" : "Developers",
"description": "Group for developers",
"members_count": 2,
"system": false,
"created_at": "2024-08-02T13:35:11.691-07:00",
"updated_at": "2024-08-02T13:35:11.691-07:00"
}
],
"total": 2,
"page": {
"number": 1,
"size": 100
}
}
# Get collaborator group details
ALL COLLABORATORS
The All collaborators
group defines the default access granted to all collaborators. Each data center assigns a unique ID to All collaborators
. Use the List collaborator groups endpoint to retrieve the All collaborators
group ID.
Retrieves a collaborator group by its ID.
GET /api/user_groups/:id
# Path parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the collaborator group to retrieve. |
# Sample request
curl -X GET 'https://www.workato.com/api/user_groups/am-WxEKCibh-dTXBtz' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"data": {
"id": "am-WxEKCibh-dTXBtz",
"name" : "Developers",
"description": "Group for developers",
"members_count": 2,
"system": false,
"created_at": "2024-08-02T13:35:11.691-07:00",
"updated_at": "2024-08-02T13:35:11.691-07:00"
}
}
# Create a collaborator group
Creates a new collaborator group.
POST /api/user_groups
# Request body
Name | Type | Description |
---|---|---|
user_group | object required | Defines the collaborator group to create. |
user_group[name] | string required | The collaborator group name. The maximum length is 200 characters. |
user_group[description] | string optional | The collaborator group description. The maximum length is 300 characters. |
# Sample request
curl -X POST 'https://www.workato.com/api/user_groups' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"user_group": {
"name": "Developers",
"description": "Group for developers"
}
}'
# Response
{
"data": {
"id": "am-WxEKCibh-dTXBtz",
"name" : "Developers",
"description": "Group for developers",
"members_count": 1,
"system": false,
"created_at": "2024-08-02T13:35:11.691-07:00",
"updated_at": "2024-08-02T13:35:11.691-07:00"
}
}
400 BAD REQUEST
A 400 Bad Request
error indicates that the server couldn't process the request due to client-side issues. Common causes include malformed requests, invalid fields, or violations of field constraints, such as unsupported data types.
In the following example, the request fails because the required name
parameter is blank:
{
"errors": [
{
"code": "bad_request",
"title": "Name can't be blank"
}
]
}
# Update a collaborator group
Updates a collaborator group by its ID.
PUT /api/user_groups/:id
# Path parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the collaborator group to update. |
# Request body
Name | Type | Description |
---|---|---|
user_group | object required | Defines the updated collaborator group. |
user_group[name] | string required | The updated name of the collaborator group. The maximum length is 200 characters. |
user_group[description] | string optional | The updated description of the collaborator group. The maximum length is 300 characters. |
# Sample request
curl -X PUT 'https://www.workato.com/api/user_groups/am-WxEKCibh-dTXBtz' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"user_group": {
"name": "Developers Team",
"description": "Team"
}
}'
# Response
{
"data": {
"id": "am-WxEKCibh-dTXBtz",
"name" : "Developers Team",
"description": "Team",
"members_count": 2,
"system": false,
"created_at": "2024-08-02T13:35:11.691-07:00",
"updated_at": "2024-08-02T13:35:11.691-07:00"
}
}
400 BAD REQUEST
A 400 Bad Request
error indicates that the server couldn't process the request due to client-side issues. Common causes include malformed requests, invalid fields, or violations of field constraints, such as unsupported data types.
In the following example, the request fails because the required name
parameter is blank:
{
"errors": [
{
"code": "bad_request",
"title": "Name can't be blank"
}
]
}
# Delete a collaborator group
Deletes a collaborator group by its ID. When you delete a collaborator group, members lose project access unless they have additional access from another source.
ALL COLLABORATORS
The All collaborators
group defines the default access granted to all collaborators. You can't delete this group.
DELETE /api/user_groups/:id
# Path parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the collaborator group to delete. |
# Sample request
curl -X DELETE 'https://www.workato.com/api/user_groups/am-WxEKCibh-dTXBtz' \
-H 'Authorization: Bearer <api_token>'
# Response
A successful request returns a 204 No Content
status code. The collaborator group is deleted, and the response body is empty.
# List collaborator group members
Retrieves members of a collaborator group.
GET /api/user_groups/:id/members
# Path parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the collaborator group to retrieve members from. |
# Query parameters
Name | Type | Description |
---|---|---|
text | string optional | Filter members by their name or email. |
page[number] | integer optional | The page number to retrieve. The default value is 1 . |
page[size] | integer optional | The number of items per page to retrieve. The default and maximum value is 100 . |
# Sample request
curl -X GET 'https://www.workato.com/api/user_groups/am-WxEKCibh-dTXBtz/members?page[number]=1&page[size]=100' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"data": [
{
"user_id": 1,
"member_invitation_id": null,
"name" : "Dani",
"email": "[email protected]",
"type": "User",
"avatar_url": "url"
},
{
"user_id": null,
"member_invitation_id": 1,
"name" : "Alex",
"email": "[email protected]",
"type": "MemberInvitation",
"avatar_url": null
}
],
"total": 2,
"page": {
"number": 1,
"size": 100
}
}
# Add members to a collaborator group
Adds collaborators to an existing collaborator group by their IDs.
POST /api/user_groups/:id/members
# Path parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the collaborator group to add members to. |
# Request body
Name | Type | Description |
---|---|---|
user_ids | array of integers required | The user IDs of members to add to the group. |
# Sample request
curl -X POST 'https://www.workato.com/api/user_groups/am-WxEKCibh-dTXBtz/members' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"user_ids": [1, 2]
}'
# Response
A successful request returns { "data": null }
. This response indicates the operation succeeded, but no additional data is returned.
# Remove members from a collaborator group
Removes collaborators from a collaborator group by their IDs.
DELETE /api/user_groups/:id/members
# Path parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the collaborator group to retrieve members from. |
# Request body
Name | Type | Description |
---|---|---|
user_ids | array of integers conditionally required | The user IDs of members to remove from the group. |
member_invitation_ids | array of integers conditionally required | A list of IDs for collaborator group invitations. Members who were added by the invitations are removed from the group. |
CONDITIONAL REQUIREMENTS
Requests must include either user_ids
or member_invitation_ids
to specify which collaborators to remove from the group. You may include both to remove collaborators based on multiple criteria.
# Sample request
curl -X DELETE 'https://www.workato.com/api/user_groups/am-WxEKCibh-dTXBtz/members?user_ids[]=1&user_ids[]=2&member_invitation_ids[]=1&member_invitation_ids[]=2' \
-H 'Authorization: Bearer <api_token>'
# Response
A successful request returns a 204 No Content
status code. The API removes the member from the collaborator group and returns no content in the response body.
# List a collaborator group's project grants
Retrieves project roles assigned to a collaborator group.
PROJECT GRANTS
A project grant assigns a project role to a collaborator or group. Refer to Project grants to manage project grants using the developer API or Manage project access and roles to manage project roles in the UI.
GET /api/user_groups/:id/project_grants
# Path parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the collaborator group whose project grants to retrieve. |
# Query parameters
Name | Type | Description |
---|---|---|
page[number] | integer optional | The page number to retrieve. The default value is 1 . |
page[size] | integer optional | The number of items per page to retrieve. The default and maximum value is 100 . |
# Sample request
curl -X GET 'https://www.workato.com/api/user_groups/pg-AQAEnmMX-b4rPeT/project_grants?page[number]=1&page[size]=100' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"data": [
{
"id": "pg-AQAEnmMX-b4rPeT",
"project": {
"id": 178229,
"name": "Development",
"environment": {
"id": 148425,
"type": "dev"
}
},
"project_role": {
"id": "pr-AQAEnmK3-EQpeYM",
"name": "Developers"
}
},
{
"id": "pg-AQAEnmKE-xpCFwT",
"project": {
"id": 178230,
"name": "Development",
"environment": {
"id": 148426,
"type": "prod"
},
},
"project_role": {
"id": "pr-AQAEnmK3-EQpeYM",
"name": "Developers"
}
}
],
"total": 2,
"page": {
"number": 1,
"size": 100
}
}
Last updated: 9/17/2025, 4:00:52 PM