Product UpdatesStatus PageWorkato Academy
English
Get a trial

# Embedded API - Role-based access control

EARLY ACCESS FEATURE

This documentation covers a feature currently in limited preview. The access control model is under active development and may change. To participate in early access testing, contact your Customer Success Manager to add you to the early adopters list.

Workato has introduced a new access control model that replaces legacy system and custom roles. This model separates permissions into environment roles and project roles to support flexible and environment-specific access control. Refer to the Manage workspace collaborators with role-based access control guide for more information on the new model.

Refer to the following sections to manage collaborators and roles in customer workspaces using the Embedded API:

Refer to the Embedded API - Role-based access control guide to manage collaborators and roles using the Workato Developer API.

# Collaborators

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

API CLIENT ACCESS

API clients require access to the DEV environment to manage collaborators. Refer to Create a client role to configure an API client's access.

# Quick reference

Type Resource Description
POST /api/managed_users/:managed_user_id/member_invitation Invite a collaborator to a customer workspace.
GET /api/managed_users/:managed_user_id/members Get a list of collaborators in a customer workspace.
GET /api/managed_users/:managed_user_id/members/:id Get customer workspace collaborator details.
POST /api/managed_users/:managed_user_id/members Add collaborator to customer workspace.
PUT /api/managed_users/:managed_user_id/members/:id Update customer workspace collaborator.
DELETE /api/managed_users/:managed_user_id/members/:id Remove collaborator from customer workspace.
GET /api/managed_users/:managed_user_id/members/
:id/project_grants		 List a customer workspace's project grants.
GET /api/managed_users/:managed_user_id/members/
:id/privileges		 Get privileges from a customer workspace collaborator.
GET /api/managed_users/:managed_user_id/members/
:id/projects_privileges		 Get projects privileges from a customer workspace collaborator.

# Invite a collaborator to a customer workspace

EXISTING ENDPOINT

The following is an existing endpoint with new updates in this release.

Invite a collaborator to an Embedded customer workspace. The API sends an email invitation if the email you provide doesn't belong to an existing user. Collaborators can join the workspace after they create a Workato account. You can invite a specific email and workspace combination once every twenty minutes. Alternatively, you can use the Add collaborator endpoint to add a collaborator directly.

POST /api/managed_users/:managed_user_id/member_invitation

# 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

NEW PARAMETERS

This endpoint now supports the env_roles[role_type] and user_group_ids parameters.

Name Type Description
name string
required		 The name of the collaborator.
email string
required		 The email of the collaborator.
env_roles object
conditional		 Configures the collaborator's environment roles. Required if role_name is not provided.
env_roles[environment_type] string
conditional		 The type of environment in the workspace where you plan to invite the collaborator. Use dev for single-environment workspaces. Required if role_name is not provided.
env_roles[name] string
conditional		 The role to assign the collaborator for the specific environment. Required if role_name is not provided.
env_roles[role_type] string
optional		 The type of role to assign the collaborator. Accepted values include privilege_group and environment. The default value is privilege_group.
role_name string
conditional		 The role to assign the collaborator. Required if env_roles is not provided.
user_group_ids array of strings
optional		 The IDs of collaborator groups to assign.

SPECIFY ROLES FOR DIFFERENT ENVIRONMENTS

You must provide either role_name or env_roles in the payload:

-role_name assigns a role in the dev environment only. -env_roles lets you specify roles for different environments.

You can't combine role_name and env_roles in the same request. If both are included, Workato assigns only the roles in env_roles and ignores role_name.

# Sample request

curl -X POST 'https://www.workato.com/api/managed_users/19029/member_invitation' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Josh",
        "email": "[email protected]",
        "user_group_ids": [
          "am-WxEKCibh-dTXBtz", 
          "am-APNHJbmM-hfhTD8"
        ],
        "env_roles": [
          { 
            "environment_type": "dev", 
            "name": "Admin", 
            "role_type": "privilege_group" 
          }
        ]
      }'

# Response

{
    "result": "ok"
}

# Get a list of collaborators in a customer workspace

EXISTING ENDPOINT

The following is an existing endpoint with new updates in this release.

Retrieve a list of all collaborators in an Embedded customer workspace.

GET /api/managed_users/:managed_user_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.

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/19029/members' \
      -H 'Authorization: Bearer <api_token>'

# Response

[
  {
    "id": 1680,
    "grant_type": "team",
    "role_name": "Admin",
    "external_id": null,
    "name": "Rosario",
    "email": "[email protected]",
    "time_zone": "Pacific Time (US & Canada)",
    "user_groups": [
      {
        "id": "ug-APHDLfHB-dTXBtz",
        "name" : "All collaborators",
        "system": true  
      },
      {
        "id": "ug-APHDLfHB-dTXBtg",
        "name" : "Developers",
        "system": false
      }
    ],
    "env_roles": [
      {
        "environment_type": "dev",
        "name": "Admin",
        "role_type": "privilege_group"
      }
    ]
  },
  {
    "id": 2641,
    "grant_type": "customer_manager",
    "role_name": "Admin",
    "external_id": null,
    "name": "Noam",
    "email": "[email protected]",
    "time_zone": "Eastern Time (US & Canada)",
    "user_groups": [
      {
        "id": "ug-APHDLfHB-dTXBtz",
        "name" : "All collaborators",
        "system": true  
      }
    ],
    "env_roles": [
      {
        "environment_type": "dev",
        "name": "Admin",
        "role_type": "privilege_group"
      }
    ]
  }
]
New properties

The following properties are new additions to the API response:

[
  {
    //...existing response...
    "user_groups": [
      {
        "id": "ug-APHDLfHB-dTXBtz",
        "name" : "All collaborators",
        "system": true  
      },
      {
        "id": "ug-APHDLfHB-dTXBtg",
        "name" : "Developers",
        "system": false
      }
    ],
    "env_roles": [
      {
        "environment_type": "dev",
        "name": "Admin",
        "role_type": "privilege_group"
      }
    ]
  },
  //...second collaborator...
]

# Get customer workspace collaborator details

EXISTING ENDPOINT

The following is an existing endpoint with new updates in this release.

Retrieves a collaborator from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/members/: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 to retrieve.

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/19029/members/34567' \
      -H 'Authorization: Bearer <api_token>'

# Response

{
  "id": 1680,
  "grant_type": "team",
  "role_name": "Admin",
  "external_id": null,
  "name": "Noam",
  "email": "[email protected]",
  "time_zone": "Pacific Time (US & Canada)",
  "user_groups": [
    {
      "id": "ug-APHDLfHB-dTXBtz",
      "name" : "All collaborators",
      "system": true  
    },
    {
      "id": "ug-APHDLfHB-dTXBtg",
      "name" : "Developers",
      "system": false
    }
  ],
  "env_roles": [
    {
      "environment_type": "dev",
      "name": "Admin",
      "role_type": "privilege_group"
    }
  ]
}
New properties

The following properties are new additions to the API response:

{
  //...existing response...
  "user_groups": [
    {
      "id": "ug-APHDLfHB-dTXBtz",
      "name" : "All collaborators",
      "system": true 
    },
    {
      "id": "ug-APHDLfHB-dTXBtg",
      "name" : "Developers",
      "system": false
    }
  ],
  "env_roles": [
    {
      "environment_type": "dev",
      "name": "Admin",
      "role_type": "privilege_group"
    }
  ]
}

# Add collaborator to customer workspace

EXISTING ENDPOINT

The following is an existing endpoint with new updates in this release.

Adds a collaborator to the specified Embedded customer workspace. Alternatively, you can use the Invite a collaborator to a managed customer workspace endpoint to invite a collaborator.

POST /api/managed_users/:managed_user_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.

# Query parameters

ADD AN EXISTING USER

You must provide the oauth_id and omit the following parameters to add an existing Workato user to an embedded workspace:

  • role_name
  • external_id
  • time_zone
  • name

NEW PARAMETERS

This endpoint now supports the env_roles[role_type] parameter.

Name Type Description
role_name string
conditional		 The role to assign the member. Required if env_roles is not provided.
name string
conditional		 The full name of the member. Required when creating a new user to add to an embedded workspace.
env_roles object
conditional		 The environment roles object. Required if role_name is not provided.
env_roles[environment_type] string
conditional		 The type of environment in the customer workspace where you plan to add the member. Required if role_name is not provided.
env_roles[name] string
conditional		 The role to assign the member for the specific environment. Required if role_name is not provided.
env_roles[role_type] string
optional		 The type of role to assign the collaborator. Accepted values include privilege_group and environment. The default value is privilege_group.
oauth_id string
optional		 The identifier used for OAuth.
external_id string
optional		 The external identifier for the member.
time_zone string
optional		 The timezone name. Refer to the Timezone list section for more information. Defaults to PST if not specified.

SPECIFY ROLES FOR DIFFERENT ENVIRONMENTS

You must provide either role_name or env_roles in the payload:

-role_name assigns a role in the dev environment only. -env_roles lets you specify roles for different environments.

You can't combine role_name and env_roles in the same request. If both are included, Workato assigns only the roles in env_roles and ignores role_name.

# Sample requests

Refer to the following sections to add collaborators to specific environments:

# Using role_name
curl  -X POST https://www.workato.com/api/managed_users/27819/members \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Jack Smith",
            "role_name": "Admin",
            "external_id": "UU0239093499"
         }'
Response: Using role_name 
{
  "data": {
    "id": 12341,
    "grant_type": "team",
    "role_name": "Admin",
    "external_id": "UU0239093499",
    "name": "Jack Smith",
    "email": "[email protected]",
    "time_zone": "Pacific Time (US & Canada)",
    "created_at": "2024-09-13T07:26:48.779-07:00",
    "last_activity_log": null
  }
}
# Using env_roles
curl  -X POST https://www.workato.com/api/managed_users/27819/members \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Jack Smith",
            "env_roles": [
                {
                  "environment_type": "dev",
                  "name": "Admin",
                  "role_type": "privilege_group"
                },
                {
                  "environment_type": "test",
                  "name": "Analyst",
                  "role_type": "privilege_group"

                },
                {
                  "environment_type": "prod",
                  "name": "Operator",
                  "role_type": "privilege_group"
                }
            ],
            "external_id": "UU0239093499"
         }'
Response: Using env_roles 
{
  "data": {
    "id": 12341,
    "grant_type": "team",
    "role_name": "Admin",
    "external_id": "UU0239093499",
    "name": "Jack Smith",
    "email": "[email protected]",
    "time_zone": "Pacific Time (US & Canada)",
    "created_at": "2024-09-24T08:06:09.883-07:00",
    "last_activity_log": null,
    "env_roles": [
      {
        "environment_type": "dev",
        "name": "Admin",
        "role_type": "privilege_group"
      },
      {
        "environment_type": "test",
        "name": "Analyst",
        "role_type": "privilege_group"
      },
      {
        "environment_type": "prod",
        "name": "Operator",
        "role_type": "privilege_group"
      }
    ]
  }
}
New properties

The following properties are new additions to the API response:

{
  // ...existing response...
  "env_roles": [
        {
          // ...existing response...
          "role_type": "privilege_group"

        },
        {
          // ...existing response...
          "role_type": "privilege_group"

        },
        {
          // ...existing response...
          "role_type": "privilege_group"
        }
    ]
}

# Update customer workspace collaborator

EXISTING ENDPOINT

The following is an existing endpoint with new updates in this release.

Updates an existing collaborator and their roles in an Embedded customer workspace.

UPDATE MEMBER RESTRICTION

You can update the role_name field for any member, whether they were added manually or through the API.

However, you can only update the following fields for collaborators who don't have their own Workato workspace:

  • oauth_id
  • external_id
  • time_zone
  • name

These users exist only as collaborators in Embedded customer workspaces and don't own standalone Workato accounts.

PUT /api/managed_users/:managed_user_id/members/: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 you plan to update.

# Query parameters

NEW PARAMETERS

This endpoint now supports the env_roles[role_type] parameter.

Name Type Description
name string
optional		 The updated full name of the member.
role_name string
optional		 The updated role to assign the member.
env_roles object
required		 Defines the collaborator's updated environment roles.
env_roles[environment_type] string
required		 The type of workspace environment where you plan to update the collaborator's roles.
env_roles[name] string
required		 The role to assign the collaborator for the specific environment.
env_roles[role_type] string
optional		 The type of role to assign the collaborator. Accepted values include privilege_group and environment. The default value is privilege_group.
oauth_id string
optional		 The updated identifier used for OAuth.
external_id string
optional		 The updated external identifier for the member.
time_zone string
optional		 The updated timezone name. Refer to the Timezone list section for more information. Defaults to PST if not specified.

# Sample requests

Refer to the following sections to add collaborators to specific environments:

# Using role_name
curl  -X POST https://www.workato.com/api/managed_users/EUU0239093499/members/12341 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Jack Smith",
            "role_name": "Admin",
            "external_id": "UU0239093499"
         }'
Response: Using role_name 
{
  "data": {
    "id": 12341,
    "grant_type": "team",
    "role_name": "Admin",
    "external_id": "UU0239093499",
    "name": "Jack Smith",
    "email": "[email protected]",
    "time_zone": "Pacific Time (US & Canada)",
    "created_at": "2024-09-13T07:26:48.779-07:00",
    "last_activity_log": null
  }
}
# Using env_roles
curl  -X POST https://www.workato.com/api/managed_users/EUU0239093499/members/12341 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Jack Smith",
            "env_roles": [
                {
                  "environment_type": "dev",
                  "name": "Admin",
                  "role_type": "privilege_group"
                },
                {
                  "environment_type": "test",
                  "name": "Analyst",
                  "role_type": "privilege_group"

                },
                {
                  "environment_type": "prod",
                  "name": "Operator",
                  "role_type": "privilege_group"
                }
            ],
            "external_id": "UU0239093499"
         }'
Response: Using env_roles 
{
  "data": {
    "id": 12341,
    "grant_type": "team",
    "role_name": "Admin",
    "external_id": "UU0239093499",
    "name": "Jack Smith",
    "email": "[email protected]",
    "time_zone": "Pacific Time (US & Canada)",
    "created_at": "2024-09-24T08:06:09.883-07:00",
    "last_activity_log": null,
    "env_roles": [
      {
        "environment_type": "dev",
        "name": "Admin",
        "role_type": "privilege_group"
      },
      {
        "environment_type": "test",
        "name": "Analyst",
        "role_type": "privilege_group"
      },
      {
        "environment_type": "prod",
        "name": "Operator",
        "role_type": "privilege_group"
      }
    ]
  }
}
New properties

The following properties are new additions to the API response:

{
  // ...existing response...
  "env_roles": [
        {
          // ...existing response...
          "role_type": "privilege_group"

        },
        {
          // ...existing response...
          "role_type": "privilege_group"

        },
        {
          // ...existing response...
          "role_type": "privilege_group"
        }
    ]
}

# Remove collaborator from customer workspace

EXISTING ENDPOINT

The following is an existing endpoint with new updates in this release.

Removes a collaborator from an Embedded customer workspace.

DELETE /api/managed_users/:managed_user_id/members/: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 to remove.

# Sample request

curl -X DELETE 'https://www.workato.com/api/managed_users/19029/members/pg-AQAEnmMX-b4rPeT' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": [
    { 
      "id": "pg-AQAEnmMX-b4rPeT"
    }
  ]
}

# List a customer workspace's project grants

Retrieves all project grants from an Embedded customer workspace. This doesn't include project access granted through collaborator groups.

GET /api/managed_users/:managed_user_id/members/: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 workspace to retrieve project grants from.

# Query parameters

Name Type Description
page object
optional		 Configures pagination settings for the project grant list.
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/members/34567/project_grants?page[number]=1&page[size]=100' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": [
    { 
      "id": "pg-AQAEnmMX-b4rPeT", 
      "project": {
        "id": 178230, 
        "name": "Development",
        "environment": {
          "id": 148425, 
          "type": "dev"
        }, 
      }, 
      "project_role": { 
        "id": "pr-AQAEnmK3-EQpeYM", 
        "name": "Developers"
      }
    }, 
    {
      "id": "pg-AQAEnmKE-xpCFwT", 
      "project": {
        "id": 178230, 
        "name": "Sales",
        "environment": {
          "id": 148426, 
          "type": "prod"
        }, 
      }, 
      "project_role": {
        "id": "pr-AQAEnmK3-EQpeYM", 
        "name": "Developers"
      }
    }
  ],
  "total": 2,
  "page": {
    "number": 1,
    "size": 100
  }
}

# Get privileges from a customer workspace collaborator

EXISTING ENDPOINT

The following is an existing endpoint with new updates in this release.

Retrieves the privileges and roles of a collaborator in an Embedded customer workspace. The response returns an array of roles for each environment (for example, dev, test, and prod) with the following information:

  • Environment type
  • User role
  • All permissions assigned to the role
  • Role type

The response includes roles from both the legacy model (role_type: privilege_group) and the new model (role_type: environment).

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

# 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 whose privileges you plan to retrieve.

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/19029/members/34567/privileges' \
      -H 'Authorization: Bearer <api_token>'

# Response

{
    "data": [
        {
            "environment_type": "dev",
            "name": "Operator",
            "role_type": "privilege_group",
            "privileges": {
                "Recipes": [
                    "read",
                    "run",
                    "read_run_history"
                ],
                "Folders": [
                    "read"
                ],
                "Projects": [
                    "read"
                ],
                "Use in recipes": [
                    "all"
                ],
                "Test automation": [
                    "read"
                ]
            }
        },
        {
            "environment_type": "test",
            "name": "Operator",
            "role_type": "privilege_group",
            "privileges": {
                "Recipes": [
                    "read",
                    "run",
                    "read_run_history"
                ],
                "Folders": [
                    "read"
                ],
                "Projects": [
                    "read"
                ],
                "Use in recipes": [
                    "all"
                ],
                "Test automation": [
                    "read"
                ]
            }
        },
        {
            "environment_type": "prod",
            "name": "Operator",
            "role_type": "privilege_group",
            "privileges": {
                "Recipes": [
                    "read",
                    "run",
                    "read_run_history"
                ],
                "Folders": [
                    "read"
                ],
                "Projects": [
                    "read"
                ],
                "Use in recipes": [
                    "all"
                ],
                "Test automation": [
                    "read"
                ]
            }
        }
    ]
}
New properties

The following properties are new additions to the API response:

{
  "data": [
    {
      // ...existing response...
      "role_type": "privilege_group",
    }
  ]
}

# Get projects privileges from a customer workspace collaborator

Retrieves project-level access for a collaborator in an Embedded customer workspace. This includes access assigned directly or through membership in a collaborator group. You can use this endpoint to audit project permissions.

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

# 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 to retrieve project privileges from.

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/19029/members/34567/projects_privileges' \
      -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": [
    {
      "environment": {
        "id": 123456,
        "type": "dev"
      },
      "projects": {
        "61722": {
          "Folders": ["create", "view"]
        }
      }
    },
    {
      "environment": {
        "id": 789123,
        "type": "prod"
      },
      "projects": {
        "74137": {
          "Folders": ["view"]
        }
      }
    }
  ]
}

# Collaborator groups

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

# 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 object
optional		 Configures pagination settings for the group list.
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

SYSTEM GROUP ID

Use the List collaborator groups endpoint to retrieve the system group's ID. Each data center assigns a unique ID to the system group. You can't delete system groups.

Retrieves a collaborator group from an Embedded customer workspace.

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

# Query parameters

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.

# Query parameters

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

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 customer workspace collaborator group

Deletes a collaborator group in an Embedded customer workspace. This automatically deletes all connections between the group and projects.

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 whose members to retrieve.

# Query parameters

Name Type Description
text string
optional		 Filter members by their name or email.
page object
optional		 Configures pagination settings for the member list.
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.

# Query parameters

Name Type Description
user_ids array of integers
required		 The workspace IDs of the members to add.

# 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

{ "data": null }

# 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 whose members to remove.

# Query parameters

Name Type Description
user_ids array of integers
conditionally required		 The 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 roles assigned to a collaborator group in an Embedded customer workspace.

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 object
optional		 Configures pagination settings for the project grant list.
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
  }
}

# Environment roles

Use the following endpoints to manage environment roles in an Embedded customer workspace.

Environment roles can have the following values:

Value Definition
system Default roles provided by Workato.
custom Roles created manually within a workspace.
inheritable Custom roles from an AHQ admin or Embedded partner workspace that are inheritable by child workspaces.
inherited Roles inherited by a child workspace from its AHQ or Embedded parent.

LEGACY ROLE COMPATIBILITY

The following endpoints are only compatible with new roles where the role_type is environment.

Use the /api/managed_users/:id/roles endpoints instead to manage legacy roles where the role_type is privilege_group.

# Quick reference

Type Resource Description
GET /api/managed_users/:managed_user_id/environment_roles List environment roles in a customer workspace.
GET /api/managed_users/:managed_user_id/environment_roles/:id Get an environment role from a customer workspace.
POST /api/managed_users/:managed_user_id/environment_roles Create an environment role in a customer workspace.
PUT /api/managed_users/:managed_user_id/environment_roles/:id Update an environment role in a customer workspace.
DELETE /api/managed_users/:managed_user_id/environment_roles/:id Delete an environment role in a customer workspace.

# List environment roles in a customer workspace

Retrieves a list of environment roles from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/environment_roles

# 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 environment roles by their name.
page object
optional		 Configures pagination settings for the environment role list.
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/environment_roles?name=Developer&page[number]=1&page[size]=100' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": [
    {
      "id": 1,
      "name" : "Developer",
      "members_count": 2,
      "type": "custom",
      "created_at": "2024-08-02T13:35:11.691-07:00",
      "updated_at": "2024-08-02T13:35:11.691-07:00"
    }
  ],
  "total": 1,
  "page": {
    "number": 1,
    "size": 100
  }
}

# Get an environment role from a customer workspace

Retrieves an environment role from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/environment_roles/: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 environment role to retrieve.

# Sample request

curl -X GET 'https://www.workato.com/api/managed_users/19029/environment_roles/1' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": {
    "id": 1,
    "name" : "Developer",
    "config": { "team": { "privileges": "all" } },
    "members_count": 2,
    "type": "custom",
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T13:35:11.691-07:00"
  }
}

# Create an environment role in a customer workspace

Creates a new environment role in an Embedded customer workspace.

POST /api/managed_users/:managed_user_id/environment_roles

# 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
environment_role object
required		 Defines the environment role to create.
environment_role[name] string
required		 The name of the environment role to create. The maximum length is 200 characters.
environment_role[config] json
required		 Defines the privileges assigned to the role.
environment_role[inheritable] boolean
optional		 Inherits the role to child workspaces when set to true. The default value is false. This value can only be set to true in Admin AHQ or Embedded partner workspaces.

# Sample request

curl -X POST 'https://www.workato.com/api/managed_users/19029/environment_roles' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "environment_role": {
          "name": "Developer",
          "config": { "team": { "privileges": "all" } },
          "inheritable": false
        }
      }'

# Response

{
  "data": {
    "id": 1,
    "name" : "Developer",
    "config": { "team": { "privileges": "all" } },
    "members_count": 0,
    "type": "custom",
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T13:35:11.691-07:00"
  }
}

# Update an environment role in a customer workspace

Updates an existing environment role in an Embedded customer workspace.

PUT /api/managed_users/:managed_user_id/environment_roles/: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 environment role to update.

# Query parameters

Name Type Description
environment_role object
required		 Defines the updated environment role.
environment_role[name] string
required		 The updated name of the environment role. The maximum length is 200 characters.
environment_role[config] json
required		 Defines the updated privileges for the role.
environment_role[inheritable] boolean
optional		 Inherits the role to child workspaces when set to true. The default value is false. This value can only be set to true in Admin AHQ or Embedded partner workspaces.

# Sample request

curl -X PUT 'https://www.workato.com/api/managed_users/19029/environment_roles/1' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "environment_role": {
          "name": "Builder",
          "config": { "team": { "privileges": "all" } },
          "inheritable": false
        }
      }'

# Response

{
  "data": {
    "id": 1,
    "name" : "Builder",
    "config": { "team": { "privileges": "all" } },
    "members_count": 0,
    "type": "custom",
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T13:35:11.691-07:00"
  }
}

# Delete an environment role in a customer workspace

Deletes an environment role in an Embedded customer workspace.

DELETE /api/managed_users/:managed_user_id/environment_roles/: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 environment role to delete.

# Sample request

curl -X DELETE 'https://www.workato.com/api/managed_users/19029/environment_roles/1' \
  -H 'Authorization: Bearer <api_token>'

# Response

A successful request returns a 204 No Content status code. The API deletes the environment role and returns an empty response body.

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 role is still assigned to collaborators:

{ 
  "errors": [
    {
      "code": "bad_request",
      "title": "You can’t delete a role when collaborators are assigned to the role."
    }
  ] 
}

# Project roles

Use the following endpoints to manage project roles in an Embedded customer workspace.

Project roles can have the following values:

Value Definition
system Default roles provided by Workato.
custom Roles created manually within a workspace.
inheritable Custom roles from an AHQ admin or Embedded partner workspace that are inheritable by child workspaces.
inherited Roles inherited by a child workspace from its AHQ or Embedded parent.

# Quick reference

Type Resource Description
GET /api/managed_users/:managed_user_id/project_roles List project roles in a customer workspace.
GET /api/managed_users/:managed_user_id/project_roles/:id Get a project role from a customer workspace.
POST /api/managed_users/:managed_user_id/project_roles Create a project role in a customer workspace.
PUT /api/managed_users/:managed_user_id/project_roles/:id Update a project role in a customer workspace.
DELETE /api/managed_users/:managed_user_id/project_roles/:id Delete a project role from a customer workspace.

# List project roles in a customer workspace

Retrieves a list of project roles from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/project_roles

# 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 project roles by their name.
page object
optional		 Configures pagination settings for the project role list.
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/project_roles?name=Builder&page[number]=1&page[size]=100' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": [
    {
      "id": 1,
      "name" : "Builder",
      "members_count": 1,
      "type": "custom",
      "created_at": "2024-08-02T13:35:11.691-07:00",
      "updated_at": "2024-08-02T13:35:11.691-07:00"
    }
  ],
  "total": 1,
  "page": {
    "number": 1,
    "size": 100
  }
}

# Get a project role from a customer workspace

Retrieves a project role from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/project_roles/: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 project role to retrieve.

# Sample request

curl -X GET 'https://www.workato.com/api/managed_users/19029/project_roles/pr-APmWpgTs-dwARGH' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": {
    "id": "pr-APmWpgTs-dwARGH",
    "name" : "Developer",
    "config": { "recipe": { "privileges": "all" } },
    "members_count": 1,
    "type": "custom",
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T13:35:11.691-07:00"
  }
}

# Create a project role in a customer workspace

Creates a new project role in an Embedded customer workspace.

POST /api/managed_users/:managed_user_id/project_roles

# 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
project_role object
required		 Defines the project role to create.
project_role[name] string
required		 The name of the project role to create. The maximum length is 200 characters.
project_role[config] json
required		 Defines the privileges for the role.
project_role[inheritable] boolean
optional		 Inherits the role to child workspaces when set to true. The default value is false. This value can only be set to true in Admin AHQ or Embedded partner workspaces.

# Sample request

curl -X POST 'https://www.workato.com/api/managed_users/19029/project_roles' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "project_role": { 
          "name": "Builder",
          "config": { "recipe": { "privileges": "all" } },
          "inheritable": false
        }
      }'

# Response

{
  "data": {
    "id": "pr-APmWpgTs-dwARGH",
    "name" : "Builder",
    "config": { "recipe": { "privileges": "all" } },
    "members_count": 0,
    "type": "custom",
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T13:35:11.691-07:00"
  }
}

# Update a project role in a customer workspace

Updates an existing project role in an Embedded customer workspace.

PUT /api/managed_users/:managed_user_id/project_roles/: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 project role to update.

# Query parameters

Name Type Description
project_role object
required		 Defines the updated project role.
project_role[name] string
required		 The updated project role name. The maximum length is 200 characters.
project_role[config] json
required		 Defines the updated privileges for the project role.
project_role[inheritable] boolean
optional		 Inherits the role to child workspaces when set to true. The default value is false. This value can only be set to true in Admin AHQ or Embedded partner workspaces.

# Sample request

curl -X PUT 'https://www.workato.com/api/managed_users/19029/project_roles/pr-APmWpgTs-dwARGH' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "project_role": { 
          "name": "Builder",
          "config": { "recipe": { "privileges": "all" } },
          "inheritable": false
        }
      }'

# Response

{
  "data": {
    "id": "pr-APmWpgTs-dwARGH",
    "name" : "Builder",
    "config": { "recipe": { "privileges": "all" } },
    "members_count": 1,
    "type": "custom",
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T13:35:11.691-07:00"
  }
}

# Delete a project role from a customer workspace

Deletes a project role from an Embedded customer workspace.

DELETE /api/project_roles/: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 project role to delete.

# Sample request

curl -X DELETE 'https://www.workato.com/api/managed_users/19029/project_roles/pr-APmWpgTs-dwARGH' \
  -H 'Authorization: Bearer <api_token>'

# Response

A successful request returns a 204 No Content status code. The API deletes the project role and returns an empty response body.

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 role is still assigned to collaborators:

{ 
  "errors": [
    {
      "code": "bad_request",
      "title": "You can’t delete a role when collaborators are assigned to the role."
    }
  ] 
}

# Project grants

Use the following endpoints to manage a collaborator or group's project grants in an Embedded customer workspace.

API CLIENT ACCESS

Project grant endpoints can only assign project roles to environments and projects that the API client can access. For example, an API client assigned to the TEST environment can only manage TEST projects. Additionally, if an API client is assigned to specific projects, it can only manage those projects. Refer to Create a client role to configure an API client's access.

# What are project grants?

A project grant assigns a project role to a collaborator or group. Refer to Manage project access and roles to manage assigned project roles in the app.

# Quick reference

Type Resource Description
GET /api/managed_users/:managed_user_id/project_grants/:id Get a customer workspace project grant.
PUT /api/managed_users/:managed_user_id/project_grants/:id Update a customer workspace project grant.
DELETE /api/managed_users/:managed_user_id/project_grants/:id Delete a customer workspace project grant.
GET /api/managed_users/:managed_user_id/:id/project_grants List customer workspace project grants.
PUT /api/managed_users/:managed_user_id/projects/
:id/project_grants		 Add or update customer workspace project grants.

# Get a customer workspace project grant

Retrieves a project grant from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/project_grants/: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 project grant to retrieve.

# Sample request

curl -X GET 'https://www.workato.com/api/managed_users/19029/project_grants/pg-AQAEnmKC-Dtt9aD' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data" : {
    "id": "pg-AQAEnmKC-Dtt9aD", 
    "project": {
      "id": 178229, 
      "name": "Development",
      "environment": {
        "id": 148425, 
        "type": "dev"
      }
    }, 
    "project_role": {
      "id": "pr-AQBGCnMB-JoFtKL", 
      "name": "Developers"
    },
    "user_group": null,
    "user": {
      "id": 1,
      "name" : "Taylor",
      "email": "[email protected]"
    }
  }
}

# Update a customer workspace project grant

Updates an existing project grant in an Embedded customer workspace.

PUT /api/managed_users/:managed_user_id/project_grants/: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 project grant to update.

# Query parameters

Name Type Description
project_grant object
required		 Defines the updated project grant.
project_grant[project_role_id] string
required		 The ID of the project role to assign.

# Sample request

curl -X PUT 'https://www.workato.com/api/managed_users/19029/project_grants/pg-AQAEnmKC-Dtt9aD' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "project_grant": {
          "project_role_id": "pr-AQBGCnMB-JoFtKL"
        }
      }'

# Response

{
  "data" : {
    "id": "pg-AQAEnmKC-Dtt9aD", 
    "project": {
      "id": 178229, 
      "name": "Development",
      "environment": {
        "id": 148425, 
        "type": "dev"
      } 
    }, 
    "project_role": {
      "id": "pr-AQBGCnMB-JoFtKL", 
      "name": "Developers"
    },
    "user_group": {
      "id": "am-WxEKCibh-dTXBtz",
      "name" : "Developers",
      "system": false
    },
    "user": null
  }
}
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 role assignment already exists:

{ 
  "errors": [
    {
      "code": "bad_request",
      "title": "Assignment has already been taken"
    }
  ] 
}

# Delete a customer workspace project grant

Deletes a project grant from an Embedded customer workspace.

DELETE /api/managed_users/:managed_user_id/project_grants/: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 project grant to delete.

# Sample request

curl -X DELETE 'https://www.workato.com/api/managed_users/19029/project_grants/pg-AQAEnmKC-Dtt9aD' \
  -H 'Authorization: Bearer <api_token>'

# Response

A successful request returns a 204 No Content status code. The API deletes the project grant and returns an empty response body.

# List customer workspace project grants

Retrieves a list of project grants from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/: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 project to retrieve grants from.

# Query parameters

Name Type Description
page object
optional		 Configures pagination settings for the project grant list.
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/178229/project_grants?page[number]=1&page[size]=100' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": [
    { 
      "id": "pg-AQAEnmMX-b4rPeT", 
      "project_role": { 
        "id": "pr-AQAEnmK3-EQpeYM", 
        "name": "Developers"
      }, 
      "user": {
        "id": 1,
        "name" : "Jie",
        "email": "[email protected]"
      },
      "user_group": null
    },  
    {
      "id": "pg-AQAEnmKC-Dtt9aD", 
      "project_role": {
        "id": "pr-AQAEnmK3-EQpeYM", 
        "name": "Developers"
      },
      "user": null,
      "user_group": {
        "id": "am-WxEKCibh-dTXBtz",
        "name" : "Developers",
        "system": false
      }
    }
  ],
  "total": 2,
  "page": {
    "number": 1,
    "size": 100
  }
}

# Add or update customer workspace project grants

Adds or updates project grants for a project in an Embedded customer workspace. You can include a maximum of 100 grants in each request.

PUT /api/managed_users/:managed_user_id/projects/: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 project where you plan to add or update grants.

# Query parameters

Name Type Description
project_grants object
required		 Defines project grants for the project.
project_grants[assignment_type] string
required		 Specifies whether to assign the role to a workspace (User) or collaborator group (UserGroup).
project_grants[assignment_id] string
required		 The ID of the target workspace or collaborator group.
project_grants[project_role_id] string
required		 The ID of the role to assign.

# Sample request

curl -X PUT 'https://www.workato.com/api/managed_users/19029/projects/178229/project_grants' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "project_grants": [
          {
            "assignment_type": "User",
            "assignment_id": "1",
            "project_role_id": "pr-AQAEnmK3-EQpeYM"
          },
          {
            "assignment_type": "UserGroup",
            "assignment_id": "am-WxEKCibh-dTXBtz",
            "project_role_id": "pr-AQAEnmK3-EQpeYM"
          }
        ]
      }'

# Response

{ "data": null }
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 it includes more than 100 grants:

{
  "errors": [
    {
      "code": "bad_request",
      "title": "Max 100 project grants per request"
    }
  ]
}

# Migration tool

Use the following endpoints to convert legacy roles into environment and project roles in an Embedded customer workspace. Alternatively, you can use the in-app migration wizard.

# Quick reference

Type Resource Description
POST /api/managed_users/:managed_user_id/
roles_migration/system_roles		 Migrate system roles from a customer workspace.
POST /api/roles_migration/custom_role Migrate a custom role from a customer workspace.

# Migrate customer workspace system roles

Converts legacy system roles into environment and project roles in an Embedded customer workspace. Alternatively, you can use the in-app migration wizard to migrate system roles.

POST /api/managed_users/:managed_user_id/roles_migration/system_roles

# 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
dry_run boolean
optional		 Returns a JSON response without migrating roles when set to true. The default value is false.

# Sample request

curl -X POST 'https://www.workato.com/api/managed_users/19029/roles_migration/system_roles' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": {
    "environment_roles": [
      {
        "name": "EnvironmentAdmin",
        "config": { /* environment admin configuration */ }
      },
      {
        "name": "EnvironmentManager",
        "config": { /* environment manager configuration */ }
      },
      {
        "name": "Member",
        "config": { /* member configuration */ }
      }
    ],
    "project_roles": [
      {
        "name": "ProjectAdmin",
        "config": { /* project admin configuration */ }
      },
      {
        "name": "AdvancedBuilder",
        "config": { /* advanced builder configuration */ }
      },
      {
       "name": "ProjectOperator",
        "config": { /* project operator configuration */ }
      }
    ],
    "collaborators": [
      {
        "user_id": 1,
        "email": "[email protected]",
        "name": "Kim",
        "roles": [
          { "environment": "dev", "name": "EnvironmentAdmin" },
          { "environment": "prod", "name": "EnvironmentManager" },
          { "environment": "test", "name": "Member" }
        ]
      }
    ],
    "projects": [
      {
        "id": 101,
        "name": "Dev Project",
        "environment": "dev",
        "collaborators": [
          {
            "user_id": 1,
            "email": "[email protected]",
            "name": "Izumi",
            "project_role": "ProjectAdmin"
          }
        ]
      }
    ],
    "moderators": [
      {
        "user_id": 201,
        "email": "[email protected]",
        "name": "Sasha",
        "environment_role": "EnvironmentAdmin",
        "project_role": "ProjectAdmin"
      }
    ]
  }
}

# Migrate a customer workspace custom role

Converts legacy custom roles into environment and project roles in an Embedded customer workspace. Alternatively, you can use the in-app migration wizard to migrate custom roles.

POST /api/managed_users/:managed_user_id/roles_migration/custom_role

# 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
privilege_group_id integer
required		 The ID of the role to convert.
environment_role object
required		 Defines the environment role to create.
environment_role[name] string
required		 The name of the new environment role.
environment_role[additional_permissions] object
optional		 Specifies additional permissions for the new environment role.
project_role object
required		 Defines the project role to create.
project_role[name] string
required		 The name of the new project role.
project_role[additional_permissions] object
optional		 Specifies additional permissions for the new project role.
dry_run boolean
optional		 Returns a JSON response without migrating roles when set to true. The default value is false.

# Sample request

curl -X POST 'https://www.workato.com/api/managed_users/19029/roles_migration/custom_role' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_token>" \
  -d '{
        "privilege_group_id": 1,
        "environment_role": {
          "name": "New Environment Role",
          "additional_permissions": {
            "manage_projects": {
              "privileges": ["create", "access_control"]
            }
          }
        },
        "project_role": {
          "name": "New Project Role",
          "additional_permissions": {
            "project_administration": {
              "privileges": ["access_control"]
            }
          }
        }
      }'

# Response

{
  "data": {
    "environment_roles": [
      {
        "name": "New environment role",
        "config": {
          "lookup_table": {
            "privileges": ["read"]
          },
          "manage_projects": { 
            "privileges": ["create", "access_control"] 
          }
        }
      }
    ],
    "project_roles": [
      {
        "name": "New project role",
        "config": {
          "recipe": {
            "privileges": ["read"]
          },
          "project_administration": { 
            "privileges": ["access_control"] 
          }
        }
      }
    ],
    "collaborators": [
      {
        "user_id": 1,
        "email": "[email protected]",
        "name": "Yuri",
        "roles": [
          { "environment": "dev", "name": "New environment role" },
          { "environment": "prod", "name": "New environment role" },
          { "environment": "test", "name": "New environment role" }
        ]
      }
    ],
    "projects": [
      {
        "id": 1,
        "name": "Dev Project",
        "environment": "dev",
        "collaborators": [
          {
            "user_id": 1,
            "email": "[email protected]",
            "name": "Hao",
            "project_role": "New project role"
          }
        ]
      }
    ],
    "moderators": [
      {
        "user_id": 1,
        "email": "[email protected]",
        "name": "Lucian",
        "environment_role": "New environment role",
        "project_role": "New project role"
      }
    ]
  }
}


Last updated: 7/16/2025, 7:03:23 PM

On this page