# Project roles
Use the following endpoints to manage your project roles.
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
Project roles resource has the following rate limit:
Type | Resource | Limit |
---|---|---|
All | All Project roles endpoints | 60 requests per minute |
# Quick reference
Type | Resource | Description |
---|---|---|
GET | /api/project_roles | List project roles. |
GET | /api/project_roles/:id | Get project role details. |
POST | /api/project_roles | Create a project role. |
PUT | /api/project_roles/:id | Update a project role. |
DELETE | /api/project_roles/:id | Delete a project role. |
# List project roles
Retrieves a list of project roles from a workspace.
GET /api/project_roles
# 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/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 project role details
Retrieves a project role by its ID.
GET /api/project_roles/:id
# Path parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the project role to retrieve. |
# Sample request
curl -X GET 'https://www.workato.com/api/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
Creates a new project role.
POST /api/project_roles
# 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 assigned to 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/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
Updates an existing project role by its ID.
PUT /api/project_roles/:id
# Path parameters
Name | Type | Description |
---|---|---|
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 name of the project role. The maximum length is 200 characters. |
project_role[config] | object required | Defines the privileges assigned to 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 PUT 'https://www.workato.com/api/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
Deletes a project role by its ID.
DELETE /api/project_roles/:id
# Path parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the project role to delete. |
# Sample request
curl -X DELETE 'https://www.workato.com/api/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 some 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