Roles

# Collaborator groups

Use the following endpoints to manage collaborator groups in an Embedded customer workspace.

# Rate limits

The collaborator groups resource has the following rate limits:

Type	Resource	Limit
GET	List group project grants: /api/managed_users/:managed_user_id/ user_groups/:id/project_grants	60 requests per minute
All	All other Collaborator groups endpoints	10 requests per second

# Quick reference

Type	Resource	Description
GET	/api/managed_users/:managed_user_id/user_groups	List customer workspace collaborator groups.
GET	/api/managed_users/:managed_user_id/user_groups/:id	Get customer workspace collaborator group details.
POST	/api/managed_users/:managed_user_id/user_groups	Create a customer workspace collaborator group.
PUT	/api/managed_users/:managed_user_id/user_groups/:id	Update a customer workspace collaborator group.
DELETE	/api/managed_users/:managed_user_id/user_groups/:id	Delete a customer workspace collaborator group.
GET	/api/managed_users/:managed_user_id/user_groups/ :id/members	List collaborator group members in a customer workspace.
POST	/api/managed_users/:managed_user_id/user_groups/ :id/members	Add members to a customer workspace collaborator group.
DELETE	/api/managed_users/:managed_user_id/user_groups/ :id/members	Remove members from a customer workspace collaborator group.
GET	/api/managed_users/:managed_user_id/user_groups/ :id/project_grants	List a customer workspace collaborator group's project grants.

# List customer workspace collaborator groups

Retrieves a list of collaborator groups from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/user_groups

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.

# 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/managed_users/19029/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 customer workspace collaborator group details

Retrieves a collaborator group from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/user_groups/:id

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 customer workspace collaborator groups endpoint to retrieve the All collaborators group ID.

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the collaborator group to retrieve.

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/19029/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 customer workspace collaborator group

Creates a new collaborator group in an Embedded customer workspace.

POST /api/managed_users/:managed_user_id/user_groups

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.

# 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/managed_users/19029/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 customer workspace collaborator group

Updates a collaborator group in an Embedded customer workspace.

PUT /api/managed_users/:managed_user_id/user_groups/:id

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
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/managed_users/19029/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 customer workspace collaborator group

Deletes a collaborator group in an Embedded customer workspace. 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/managed_users/:managed_user_id/user_groups/:id

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the collaborator group to delete.

# Sample request

curl  -X DELETE 'https://www.workato.com/api/managed_users/19029/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 in a customer workspace

Retrieves members of a collaborator group in an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/user_groups/:id/members

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
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/managed_users/19029/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 customer workspace collaborator group

Adds collaborators to an existing collaborator group in an Embedded customer workspace.

POST /api/managed_users/:managed_user_id/user_groups/:id/members

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
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/managed_users/19029/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 customer workspace collaborator group

Removes collaborators from a collaborator group in an Embedded customer workspace.

DELETE /api/managed_users/:managed_user_id/user_groups/:id/members

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the collaborator group to remove members from.

# Query parameters

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/managed_users/19029/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 grants assigned to a collaborator group in an Embedded customer workspace.

PROJECT GRANTS

A project grant assigns a project role to a collaborator or group. Refer to Project grants to manage project grants using the Embedded API or Manage project access and roles to manage project grants in the UI.

GET /api/managed_users/:managed_user_id/user_groups/:id/project_grants

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
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/managed_users/19029/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: 10/23/2025, 8:27:15 PM