Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial
Developer API
Resources
Roles

Collaborator groups ​

Use the following endpoints to manage your collaborator groups.

Rate limits ​

The collaborator groups resource has the following rate limit:

Quick reference ​

TypeResourceDescription
GET/api/user_groupsList collaborator groups.
GET/api/user_groups/:idGet collaborator group details.
POST/api/user_groupsCreate a collaborator group.
PUT/api/user_groups/:idUpdate a collaborator group.
DELETE/api/user_groups/:idDelete a collaborator group.
GET/api/user_groups/:id/membersList collaborator group members.
POST/api/user_groups/:id/membersAdd members to a collaborator group.
DELETE/api/user_groups/:id/membersRemove members from a collaborator group.
GET/api/user_groups/:id/project_grantsList a collaborator group's project grants.

List collaborator groups ​

Retrieves a list of collaborator groups from a workspace.

shell
GET /api/user_groups

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/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 collaborator group details ​

Retrieves a collaborator group by its ID.

shell
GET /api/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 collaborator groups endpoint to retrieve the All collaborators group ID.

Path parameters ​

NameTypeDescription
idstring
required		The ID of the collaborator group to retrieve.

Sample request ​

shell
curl  -X GET 'https://www.workato.com/api/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 collaborator group ​

Creates a new collaborator group.

shell
POST /api/user_groups

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/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 collaborator group ​

Updates a collaborator group by its ID.

shell
PUT /api/user_groups/:id

Path parameters ​

NameTypeDescription
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/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 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.

shell
DELETE /api/user_groups/:id

Path parameters ​

NameTypeDescription
idstring
required		The ID of the collaborator group to delete.

Sample request ​

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

shell
GET /api/user_groups/:id/members

Path parameters ​

NameTypeDescription
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/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 collaborator group ​

Adds collaborators to an existing collaborator group by their IDs.

shell
POST /api/user_groups/:id/members

Path parameters ​

NameTypeDescription
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/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.

shell
DELETE /api/user_groups/:id/members

Path parameters ​

NameTypeDescription
idstring
required		The ID of the collaborator group to retrieve members from.

Request body ​

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

shell
GET /api/user_groups/:id/project_grants

Path parameters ​

NameTypeDescription
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/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: