# 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 workspace.

# Rate limits

The project roles resource has the following rate limit:

Type Resource Limit
All All Project roles endpoints10 requests per second

# 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[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.

# Request body

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] object
required
Defines the privileges for the role.
project_role[inheritable] boolean
optional
Child workspaces inherit the role 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.

# Request body

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] object
required
Defines the updated privileges for the project role.
project_role[inheritable] boolean
optional
Child workspaces inherit the role 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/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 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."
    }
  ] 
}


Last updated: 9/9/2025, 2:59:57 PM