Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial
Embedded API
Resources
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:

Quick reference ​

TypeResourceDescription
GET/api/managed_users/:managed_user_id/user_groupsList customer workspace collaborator groups.
GET/api/managed_users/:managed_user_id/user_groups/:idGet customer workspace collaborator group details.
POST/api/managed_users/:managed_user_id/user_groupsCreate a customer workspace collaborator group.
PUT/api/managed_users/:managed_user_id/user_groups/:idUpdate a customer workspace collaborator group.
DELETE/api/managed_users/:managed_user_id/user_groups/:idDelete 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.

shell
GET /api/managed_users/:managed_user_id/user_groups

Path parameters ​

NameTypeDescription
managed_user_idstring
required		The Embedded customer ID or external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.

Query parameters ​

NameTypeDescription
namestring
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 ​

shell
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 ​

json
{
  "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.

shell
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 ​

NameTypeDescription
managed_user_idstring
required		The Embedded customer ID or external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.
idstring
required		The ID of the collaborator group to retrieve.

Sample request ​

shell
curl  -X GET 'https://www.workato.com/api/managed_users/19029/user_groups/am-WxEKCibh-dTXBtz' \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
  "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.

shell
POST /api/managed_users/:managed_user_id/user_groups

Path parameters ​

NameTypeDescription
managed_user_idstring
required		The Embedded customer ID or external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.

Request body ​

NameTypeDescription
user_groupobject
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 ​

shell
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 ​

json
{
  "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:

json
{
  "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.

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

Path parameters ​

NameTypeDescription
managed_user_idstring
required		The Embedded customer ID or external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.
idstring
required		The ID of the collaborator group to update.

Request body ​

NameTypeDescription
user_groupobject
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 ​

shell
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 ​

json
{
  "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:

json
{
  "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.

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

Path parameters ​

NameTypeDescription
managed_user_idstring
required		The Embedded customer ID or external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.
idstring
required		The ID of the collaborator group to delete.

Sample request ​

shell
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.

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

Path parameters ​

NameTypeDescription
managed_user_idstring
required		The Embedded customer ID or external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.
idstring
required		The ID of the collaborator group to retrieve members from.

Query parameters ​

NameTypeDescription
textstring
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 ​

shell
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 ​

json
{
  "data": [
    {
      "user_id": 1,
      "member_invitation_id": null,
      "name" : "Dani",
      "email": "dani@workato.com",
      "type": "User",
      "avatar_url": "url"
    },
    {
      "user_id": null,
      "member_invitation_id": 1,
      "name" : "Alex",
      "email": "alex@workato.com",
      "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.

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

Path parameters ​

NameTypeDescription
managed_user_idstring
required		The Embedded customer ID or external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.
idstring
required		The ID of the collaborator group to add members to.

Request body ​

NameTypeDescription
user_idsarray of integers
required		The user IDs of members to add to the group.

Sample request ​

shell
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.

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

Path parameters ​

NameTypeDescription
managed_user_idstring
required		The Embedded customer ID or external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.
idstring
required		The ID of the collaborator group to remove members from.

Query parameters ​

NameTypeDescription
user_idsarray of integers
conditionally required		The user IDs of members to remove from the group.
member_invitation_idsarray 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 ​

shell
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.

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

Path parameters ​

NameTypeDescription
managed_user_idstring
required		The Embedded customer ID or external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.
idstring
required		The ID of the collaborator group whose project grants to retrieve.

Query parameters ​

NameTypeDescription
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 ​

shell
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 ​

json
{
  "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: