# 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 workspace. |
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
.
# Rate limits
The environment roles resource has the following rate limit:
Type | Resource | Limit |
---|---|---|
All | All Environment roles endpoints | 10 requests per second |
# 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[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 . |
# Request body
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] | object required | Defines the privileges assigned to the role. |
environment_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/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. |
# Request body
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] | object required | Defines the updated privileges for the role. |
environment_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/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."
}
]
}
Last updated: 9/9/2025, 2:59:57 PM