Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial
Developer API
Resources
Roles

Environment roles ​

Use the following endpoints to manage your environment roles.

Environment roles can have the following values:

ValueDefinition
systemDefault roles provided by Workato.
customRoles created manually within a workspace.
inheritableCustom roles from an AHQ admin or Embedded partner workspace that are inheritable by child workspaces.
inheritedRoles 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/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:

Quick reference ​

TypeResourceDescription
GET/api/environment_rolesList environment roles.
GET/api/environment_roles/:idGet environment role details.
POST/api/environment_rolesCreate an environment role.
PUT/api/environment_roles/:idUpdate an environment role.
DELETE/api/environment_roles/:idDelete an environment role.

List environment roles ​

Retrieves a list of environment roles from your workspace.

shell
GET /api/environment_roles

Query parameters ​

NameTypeDescription
namestring
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 ​

shell
curl -X GET 'https://www.workato.com/api/environment_roles?name=Developer&page[number]=1&page[size]=100' \
  -H 'Authorization: Bearer <api_token>'

Response ​

json
{
  "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.

shell
GET /api/environment_roles/:id

Path parameters ​

NameTypeDescription
idstring
required		The ID of the environment role to retrieve.

Sample request ​

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

Response ​

json
{
  "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.

shell
POST /api/environment_roles

Request body ​

NameTypeDescription
environment_roleobject
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 ​

shell
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 ​

json
{
  "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.

shell
PUT /api/environment_roles/:id

Path parameters ​

NameTypeDescription
idstring
required		The ID of the environment role to update.

Request body ​

NameTypeDescription
environment_roleobject
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 privileges assigned to the environment 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 ​

shell
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 ​

json
{
  "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.

shell
DELETE /api/environment_roles/:id

Path parameters ​

NameTypeDescription
idstring
required		The ID of the environment role to delete.

Sample request ​

shell
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:

json
{ 
  "errors": [
    {
      "code": "bad_request",
      "title": "You can’t delete a role when collaborators are assigned to the role."
    }
  ] 
}

Last updated: