Roles

# 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

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