Product UpdatesStatus PageWorkato Academy
English
Get a trial

# Developer 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 using the Workato Developer API:

Refer to the Embedded API - Role-based access control guide to manage collaborators and roles in customer workspaces using the Embedded API.

# Collaborators

Use the following endpoints to manage collaborators.

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/member_invitations Invite a collaborator to a workspace.
GET /api/members/ Get list of collaborators.
GET /api/members/:id Get collaborator details.
PUT /api/members/:id Update collaborator roles.
DELETE /api/members/:id Delete a collaborator.
GET /api/members/:id/project_grants List a workspace's project grants.
GET /api/members/:id/privileges Get collaborator privileges.
GET /api/members/:id/projects_privileges Get collaborator projects privileges.

# Invite a collaborator

EXISTING ENDPOINT

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

Invite a collaborator to your 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.

POST /api/member_invitations

# 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
required		 Defines the collaborator's environment roles.
env_roles[environment_type] string
required		 The type of environment in the workspace where you plan to invite the collaborator. Use dev for single-environment workspaces.
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.
role_name string
deprecated		 This field is deprecated. Use env_roles instead, even for single-environment workspaces.
user_group_ids array of strings
optional		 The IDs of collaborator groups to assign.

# Sample request

curl -X POST 'https://www.workato.com/api/member_invitations' \
  -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 list of collaborators

EXISTING ENDPOINT

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

Retrieve a list of all collaborators in a workspace.

GET /api/members

# Query parameters

Name Type Description
email string
optional		 Filters the list to collaborators whose email contains the provided value. Special characters must be URL-encoded.

# Sample request

curl  -X GET 'https://www.workato.com/api/members?email=example.com' \
      -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": [
    {
      "id": 12345,
      "grant_type": "federation_manager",
      "user_groups": [
        {
          "id": "am-WxEKCibh-dTXBtz",
          "name": "All collaborators",
          "system": true
        },
        {
          "id": "am-WxEKCibh-dTXBtg",
          "name": "Developers",
          "system": false
        }
      ],
      "roles": [
        {
          "environment_type": "dev",
          "role_name": "Admin",
          "role_type": "privilege_group"
        },
        {
          "environment_type": "test",
          "role_name": "Admin",
          "role_type": "privilege_group"
        },
        {
          "environment_type": "prod",
          "role_name": "Admin",
          "role_type": "privilege_group"
        }
      ],
      "last_activity_log": {
        "id": 2807129,
        "event_type": "user_login",
        "created_at": "2024-03-07T16:38:18.414-08:00"
      },
      "external_id": null,
      "name": "Rosario",
      "email": "[email protected]",
      "time_zone": "Pacific Time (US & Canada)",
      "created_at": "2021-12-14T13:01:15.935-08:00"
    },
    {
      "id": 23456,
      "grant_type": "team",
      "user_groups": [
        {
          "id": "am-WxEKCibh-dTXBtz",
          "name": "All collaborators",
          "system": true
        },
        {
          "id": "am-WxEKCibh-dTXBtg",
          "name": "Developers",
          "system": false
        }
      ],
      "roles": [
        {
          "environment_type": "dev",
          "role_name": "IT_Developer",
          "role_type": "privilege_group"
        },
        {
          "environment_type": "test",
          "role_name": "No access",
          "role_type": "privilege_group"
        },
        {
          "environment_type": "prod",
          "role_name": "No access",
          "role_type": "privilege_group"
        }
      ],
      "last_activity_log": {
        "id": 2807129,
        "event_type": "user_login",
        "created_at": "2024-03-07T16:38:18.414-08:00"
      },
      "external_id": null,
      "name": "Noam",
      "email": "[email protected]",
      "time_zone": "Pacific Time (US & Canada)",
      "created_at": "2021-1-12T13:01:15.935-08:00"
    }
  ],
  "total": 2
}
New properties

The following properties are new additions to the API response:

{
  "data": [
    {
      // ...existing response...
      "user_groups": [
        {
          "id": "am-WxEKCibh-dTXBtz",
          "name" : "All collaborators",
          "system": true  
        },
        {
          "id": "am-WxEKCibh-dTXBtg",
          "name" : "Developers",
          "system": false
        }
      ],
      "roles": [
        // ...existing response...
        {
          "environment_type": "dev",
          "role_name": "Admin",
          "role_type": "privilege_group"
        }
      ]
    },
   // ...second collaborator....
  ],
  "total": 2
}

# Get collaborator details

EXISTING ENDPOINT

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

Retrieves a collaborator by their ID.

GET /api/members/:id

# Path parameters

Name Type Description
id string
required		 The ID of the collaborator to retrieve.

# Sample request

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

# Response

{
  "data": {
    "id": 34567,
    "grant_type": "team",
    "user_groups": [
      {
        "id": "am-WxEKCibh-dTXBtz",
        "name": "All collaborators",
        "system": true
      },
      {
        "id": "am-WxEKCibh-dTXBtg",
        "name": "Developers",
        "system": false
      }
    ],
    "roles": [
      {
        "environment_type": "dev",
        "role_name": "HR_Developer",
        "role_type": "privilege_group"
      },
      {
        "environment_type": "test",
        "role_name": "HR_Viewer",
        "role_type": "privilege_group"
      },
      {
        "environment_type": "prod",
        "role_name": "Operator",
        "role_type": "privilege_group"
      }
    ],
    "last_activity_log": {
      "id": 2807147,
      "event_type": "user_login",
      "created_at": "2024-03-07T16:44:39.318-08:00"
    },
    "external_id": null,
    "name": "Dana",
    "email": "[email protected]",
    "time_zone": "Pacific Time (US & Canada)",
    "created_at": "2019-09-09T00:45:17.019-07:00"
  }
}
New properties

The following properties are new additions to the API response:

{
  "data": {
    // ...existing response...
    "user_groups": [
      {
        "id": "am-WxEKCibh-dTXBtz",
        "name" : "All collaborators",
        "system": true  
      },
      {
        "id": "am-WxEKCibh-dTXBtg",
        "name" : "Developers",
        "system": false
      }
    ],
    "roles": [
      // ...existing response...
      {
        "environment_type": "dev",
        "role_name": "Admin",
        "role_type": "privilege_group"
      }
    ]
  }
}

# Update collaborator roles

EXISTING ENDPOINT

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

Updates an existing collaborator's roles by their ID. To remove a collaborator's access, include NoAccess in the request payload.

PUT /api/members/:id

# Path parameters

Name Type Description
id string
required		 The ID of the collaborator whose roles you plan to update.

# Query parameters

NEW PARAMETERS

This endpoint now supports the env_roles[role_type] parameter.

Name Type Description
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.

WORKSPACES WITHOUT ENVIRONMENTS ENABLED

For workspaces that do not have environments enabled, use dev as the environment_type.

# Sample request

curl -X PUT 'https://www.workato.com/api/members/34567' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "env_roles": [
          {
            "environment_type": "dev",
            "name": "Admin",
            "role_type": "privilege_group"
          }
        ]
      }'

# Response

{
    "data": {
        "result": "ok"
    }
}

# Delete a collaborator

Deletes a collaborator by their ID.

DELETE /api/members/:id

# Path parameters

Name Type Description
id string
required		 The ID of the collaborator to delete.

# Sample request

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

# Response

A successful request returns a 204 No Content status code. The collaborator is deleted, and the response body is empty.

# List a workspace's project grants

Retrieves all project grants for a workspace. This doesn't include project access granted through collaborator groups.

GET /api/members/:id/project_grants

# Path parameters

Name Type Description
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/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 collaborator privileges

EXISTING ENDPOINT

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

Retrieves the privileges and roles of a collaborator by their ID. 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/members/:id/privileges

# Path parameters

Name Type Description
id string
required		 The ID of the collaborator whose privileges you plan to retrieve.

# Sample request

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

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

GET /api/members/:id/projects_privileges

# Path parameters

Name Type Description
id string
required		 The ID of the collaborator whose project privileges you plan to retrieve.

# Sample request

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

# Quick reference

Type Resource Description
GET /api/user_groups List collaborator groups.
GET /api/user_groups/:id Get collaborator group details.
POST /api/user_groups Create a collaborator group.
PUT /api/user_groups/:id Update a collaborator group.
DELETE /api/user_groups/:id Delete a collaborator group.
GET /api/user_groups/:id/members List collaborator group members.
POST /api/user_groups/:id/members Add members to a collaborator group.
DELETE /api/user_groups/:id/members Remove members from a collaborator group.
GET /api/user_groups/:id/project_grants List a collaborator group's project grants.

# List collaborator groups

Retrieves a list of collaborator groups from a workspace.

GET /api/user_groups

# 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/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 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 by its ID.

GET /api/user_groups/:id

# Path parameters

Name Type Description
id string
required		 The ID of the collaborator group to retrieve.

# Sample request

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

Creates a new collaborator group.

POST /api/user_groups

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

Updates a collaborator group by its ID.

PUT /api/user_groups/:id

# Path parameters

Name Type Description
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/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 collaborator group

Deletes a collaborator group by its ID. This automatically deletes all connections between the group and projects.

DELETE /api/user_groups/:id

# Path parameters

Name Type Description
id string
required		 The ID of the collaborator group to delete.

# Sample request

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.

GET /api/user_groups/:id/members

# Path parameters

Name Type Description
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/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 collaborator group

Adds collaborators to an existing collaborator group by their IDs.

POST /api/user_groups/:id/members

# Path parameters

Name Type Description
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 members to add.

# Sample request

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

{ "data": null }

# Remove members from a collaborator group

Removes collaborators from a collaborator group by their IDs.

DELETE /api/user_groups/:id/members

# Path parameters

Name Type Description
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/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.

GET /api/user_groups/:id/project_grants

# Path parameters

Name Type Description
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/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 your environment roles.

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/roles endpoints instead to manage legacy roles where the role_type is privilege_group.

# Quick reference

Type Resource Description
GET /api/environment_roles List environment roles.
GET /api/environment_roles/:id Get environment role details.
POST /api/environment_roles Create an environment role.
PUT /api/environment_roles/:id Update an environment role.
DELETE /api/environment_roles/:id Delete an environment role.

# List environment roles

Retrieves a list of environment roles from your workspace.

GET /api/environment_roles

# 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/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 environment role details

Retrieves an environment role by its ID.

GET /api/environment_roles/:id

# Path parameters

Name Type Description
id string
required		 The ID of the environment role to retrieve.

# Sample request

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

Creates a new environment role.

POST /api/environment_roles

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

Updates an existing environment role by its ID.

PUT /api/environment_roles/:id

# Path parameters

Name Type Description
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 privileges assigned to the environment 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/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

Deletes an environment role by its ID.

DELETE /api/environment_roles/:id

# Path parameters

Name Type Description
id string
required		 The ID of the environment role to delete.

# Sample request

curl -X DELETE 'https://www.workato.com/api/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 some 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 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.

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

# 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 assigned to 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/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.

# Query parameters

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] json
required		 Defines the privileges assigned to 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 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."
    }
  ] 
}

# Project grants

Use the following endpoints to manage a collaborator or group's project grants.

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/project_grants/:id Get a project grant.
PUT /api/project_grants/:id Update a project grant.
DELETE /api/project_grants/:id Delete a project grant.
GET /api/projects/:id/project_grants List project grants.
PUT /api/projects/:id/project_grants Add or update project grants.

# Get a project grant

Retrieves a project grant by its ID.

GET /api/project_grants/:id

# Path parameters

Name Type Description
id string
required		 The ID of the project grant to retrieve.

# Sample request

curl -X GET 'https://www.workato.com/api/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 project grant

Updates an existing project grant by its ID.

PUT /api/project_grants/:id

# Path parameters

Name Type Description
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/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 assignment is already taken:

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

# Delete a project grant

Deletes a project grant by its ID.

DELETE /api/project_grants/:id

# Path parameters

Name Type Description
id string
required		 The ID of the project grant to delete.

# Sample request

curl -X DELETE 'https://www.workato.com/api/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 project grants

Retrieves a list of grants from a project by its ID.

GET /api/projects/:id/project_grants

# Path parameters

Name Type Description
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/projects/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 project grants

Adds or updates project grants for a project by its ID. You can include a maximum of 100 grants in each request.

PUT /api/projects/:id/project_grants

# Path parameters

Name Type Description
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/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 exceeds the maximum number of grants per request:

{
  "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. Alternatively, you can use the in-app migration wizard.

# Quick reference

Type Resource Description
POST /api/roles_migration/system_roles Migrate system roles.
POST /api/roles_migration/custom_role Migrate a custom role.

# Migrate system roles

Converts legacy system roles into environment and project roles. You can also use the in-app migration wizard to migrate system roles.

POST /api/roles_migration/system_roles

# 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/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 custom role

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

POST /api/roles_migration/custom_role

# 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/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, 8:12:46 PM

On this page