Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial

RBAC 2.0 migration - Developer and Embedded API changes ​

Workato is migrating workspaces to the new role-based access control model, which replaces legacy system roles (Admin, Analyst, Operator) with environment roles and project roles. This document lists the Developer API and Embedded API payload and response changes that take effect after a workspace completes this migration.

ACTION REQUIRED

After your workspace migrates, these endpoints no longer accept the role_name parameter or env_roles[role_type]: "privilege_group". Update integrations to use env_roles with role_type: "environment" before your workspace migrates to avoid disruptions.

Does this affect me? ​

This affects your integration if it uses any of the following with the Developer API or Embedded API:

  • The role_name parameter to invite or update a collaborator
  • env_roles[role_type] set to privilege_group
  • Legacy role names, such as Admin, Analyst, or Operator, that don't exist as custom environment roles in your workspace
  • The legacy roles endpoints (/api/roles, /api/managed_users/:managed_user_id/roles) or the role migration endpoints (/api/roles_migration/*)

NOT YET MIGRATED

If your workspace hasn't been migrated yet, continue using the existing Workspace collaborators, Legacy roles, and Embedded API - Manage customers documentation. The changes on this page don't apply until your workspace completes migration. Contact your customer success manager or Workato Support for migration guidance.

Developer API changes ​

These changes affect collaborator and legacy role endpoints in the Developer API, used to manage collaborators and roles in your own workspace.

Invite a collaborator ​

After migration, the Invite a collaborator endpoint requires env_roles with role_type: "environment". It no longer accepts role_name or role_type: "privilege_group".

Legacy format (rejected after migration):

shell
curl --location 'https://YOUR_DATA_CENTER/api/member_invitations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_token>' \
  --data-raw '{
        "name": ":name",
        "email": ":email",
        "env_roles": [
          {
            "environment_type": "dev",
            "name": "Member",
            "role_type": "privilege_group"
          }
        ]
      }'

New format (required):

shell
curl --location 'https://YOUR_DATA_CENTER/api/member_invitations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_token>' \
  --data-raw '{
        "name": ":name",
        "email": ":email",
        "env_roles": [
          {
            "environment_type": "dev",
            "name": "Member",
            "role_type": "environment"
          }
        ]
      }'

If you pass env_roles[role_type]: "privilege_group" for a role name that only exists as an environment role, the endpoint returns a 400 error:

json
{
  "message": "Role Member not found. If this is an RBAC 2.0 environment role, pass it via env_roles with role_type: \"environment\"."
}

If you pass a legacy role name, such as Admin, Analyst, or Operator, that no longer exists after migration, the endpoint returns a 400 error:

json
{
  "message": "Legacy roles can't be created, edited or used after migration"
}

Update collaborator roles ​

After migration, the Update collaborator roles endpoint no longer accepts role_type: "privilege_group". Pass env_roles with role_type: "environment" instead.

Legacy format (rejected after migration):

shell
curl --location --request PUT 'https://YOUR_DATA_CENTER/api/members/:id' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  --data '{
        "env_roles": [
          {
            "environment_type": "dev",
            "name": "Analyst",
            "role_type": "privilege_group"
          }
        ]
      }'

New format (required):

shell
curl --location --request PUT 'https://YOUR_DATA_CENTER/api/members/:id' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  --data '{
        "env_roles": [
          {
            "environment_type": "dev",
            "name": "Member",
            "role_type": "environment"
          }
        ]
      }'

Legacy roles ​

The Legacy roles endpoints are deprecated after migration, since a migrated workspace no longer has legacy custom roles to list, copy, or update.

EndpointBehavior after migration
GET /api/rolesReturns a 200 OK status with an empty response.
POST /api/roles/:id/copyReturns a 400 error.
PUT /api/roles/:idReturns a 400 error.
GET /api/members/:id/privilegesReturns environment-level privileges only. Use Get collaborator project privileges to retrieve project-level access.

Use Environment roles and Project roles to manage roles instead.

Role migration ​

The Role migration endpoints are deprecated after migration, since a migrated workspace has no remaining legacy roles to migrate.

Embedded (OEM) API changes ​

These changes affect the same collaborator and legacy role endpoints in the Embedded API, scoped to managed_users and used to manage collaborators and roles in your customers' workspaces.

Invite a collaborator to a customer workspace ​

After migration, the Invite a collaborator to a customer workspace endpoint requires env_roles with role_type: "environment". It no longer accepts role_name or role_type: "privilege_group".

Legacy format (rejected after migration):

shell
curl --location 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/member_invitations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_token>' \
  --data-raw '{
        "name": ":name",
        "email": ":email",
        "role_name": "Admin"
      }'

New format (required):

shell
curl --location 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/member_invitations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_token>' \
  --data-raw '{
        "name": ":name",
        "email": ":email",
        "env_roles": [
          {
            "environment_type": "dev",
            "name": "Environment manager",
            "role_type": "environment"
          }
        ]
      }'

Add a collaborator to a customer workspace ​

After migration, the Add collaborator to customer workspace endpoint requires env_roles with role_type: "environment". It no longer accepts role_name or role_type: "privilege_group".

Legacy format (rejected after migration):

shell
curl --location 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/members' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_token>' \
  --data-raw '{
        "name": ":name",
        "role_name": "Admin",
        "external_id": ":external_id"
      }'

New format (required):

shell
curl --location 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/members' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_token>' \
  --data-raw '{
        "name": ":name",
        "external_id": ":external_id",
        "env_roles": [
          {
            "environment_type": "dev",
            "name": "Environment manager",
            "role_type": "environment"
          }
        ]
      }'

Update a customer workspace collaborator ​

After migration, the Update customer workspace collaborator endpoint requires env_roles with role_type: "environment". It no longer accepts role_name or role_type: "privilege_group".

Legacy format (rejected after migration):

shell
curl --location --request PUT 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/members/:member_id' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  --data '{
        "role_name": "Admin"
      }'

New format (required):

shell
curl --location --request PUT 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/members/:member_id' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  --data '{
        "env_roles": [
          {
            "environment_type": "dev",
            "name": "Environment admin",
            "role_type": "environment"
          }
        ]
      }'

Legacy roles ​

The Embedded API - Legacy roles endpoints are deprecated after migration, since a migrated customer workspace no longer has legacy custom roles to list or copy.

EndpointBehavior after migration
GET /api/managed_users/:managed_user_id/rolesReturns a 200 OK status with an empty response.
POST /api/managed_users/:managed_user_id/roles/:role_id/copyReturns a 400 error.
GET /api/managed_users/:managed_user_id/members/:member_id/privilegesReturns environment-level privileges only. Use Get projects privileges from a customer workspace collaborator to retrieve project-level access.

Use Embedded API - Environment roles and Embedded API - Project roles to manage roles instead.

Last updated: