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."
    }
  ] 
}