From 0d5f1d3ace5a1605cb72f43dce87420e1af507f0 Mon Sep 17 00:00:00 2001 From: John Allers Date: Thu, 20 Aug 2026 18:08:12 +0000 Subject: [PATCH 1/5] docs: add prominent RBAC v2 migration instructions for Workato connector Workato is deprecating legacy roles at the end of August 2026, and every workspace must migrate to the RBAC v2 (environment roles) model. Add a prominent warning with a same-day cutover checklist so customers don't hit the failed to list environment roles: 401 error by enabling Environment roles sync too early, or silently drop environment role grants by disabling it too late. Also trims two footnotes that duplicated the new guidance. Ref: CXP-961 Co-authored-by: c1-squire-dev[bot] --- docs/connector.mdx | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/connector.mdx b/docs/connector.mdx index c839a1d7..cbf557fb 100644 --- a/docs/connector.mdx +++ b/docs/connector.mdx @@ -6,6 +6,28 @@ description: C1 provides identity governance and just-in-time provisioning for W sidebarTitle: Workato --- + +**Legacy Workato roles are being retired at the end of August 2026.** Every Workato workspace must migrate to the new RBAC v2 model (environment roles) before then. Read Workato's [Access Control v2 overview](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/access-control-v2.html) and follow their [migration guide](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/migrate-roles) to migrate your workspace. + +**Before your workspace migrates:** current releases of this connector sync all resource types by default, including **Environment roles** — so Environment roles sync is already enabled even if your workspace is still on the legacy role model. If your workspace hasn't migrated yet, exclude **Environment roles** from sync in the connector's resource type configuration. Enabling it against a legacy workspace fails sync with `failed to list environment roles: 401`, because the `/api/environment_roles` endpoint doesn't exist until after migration. + +**On the same day your workspace migrates to RBAC v2**, complete this cutover in order: + +1. In Workato, update your C1 API client's role with the permissions that only become available after migration: + - **List environment roles** — required + - **Get environment role** — required only if C1 provisions environment role assignments +2. In the connector configuration: + - Enable **Disable custom roles sync**, since custom roles are no longer served from the legacy `/api/roles` endpoint. + - Confirm **Environment roles** sync is enabled (it's on by default — re-enable it now if you excluded it per the note above). + +Getting either side of the cutover wrong fails differently: + +- Enable Environment roles sync too early (before migration) → sync fails with `failed to list environment roles: 401`. +- Leave Environment roles sync disabled too late (after migration) → sync succeeds, but environment role grants are silently dropped — collaborators will appear to have no role assignments. + +Custom roles also move from the legacy `/api/roles` resource to environment roles, a different resource type. The first sync after migration rebuilds all role resources and grants from scratch, so expect a large diff with no retained history — this is expected, not a sync error. + + ## Provision accounts When provisioning a new collaborator account, the following fields are available on the account creation form: @@ -82,11 +104,11 @@ Select the following endpoints: | | Environment roles | Get environment role†‡ | `GET /api/environment_roles/:id` | *If you don’t want to use C1 to provision role assignments, you can skip **Update collaborator’s roles** and **Get environment role**. - †**List environment roles** and **Get environment role** are only available in workspaces that use the new RBAC v2 model (environment roles). If your workspace uses the legacy role model, these permissions do not appear in the UI and you can skip them. + †**List environment roles** and **Get environment role** are only available after your workspace migrates to RBAC v2 — see the migration notice above for the full cutover sequence. ‡**Get environment role** is required only if you want C1 to provision environment role assignments. - §**The Collaborator roles section** (including **List non-system roles**) only appears in the UI if your workspace uses the legacy roles model. If this section is not visible, your workspace has migrated to the new RBAC v2 model and legacy custom roles are no longer accessible via the API. In that case, migrate your legacy custom roles to environment roles using the [Role migration API](https://docs.workato.com/workato-api/role-migration.html), or enable **Disable custom roles sync** to skip legacy custom role sync. + §**The Collaborator roles section** (including **List non-system roles**) only appears in the UI if your workspace uses the legacy roles model. If this section is not visible, your workspace has migrated to RBAC v2 — see the migration notice above, and use Workato's [Role migration API](https://docs.workato.com/workato-api/role-migration.html) to migrate your legacy custom roles to environment roles. Save the new role. From 4ba3d76e20e80f4c7548415f96f5046e545575f2 Mon Sep 17 00:00:00 2001 From: John Allers Date: Thu, 20 Aug 2026 21:04:12 +0000 Subject: [PATCH 2/5] docs: move RBAC v2 migration checklist to its own section Keep the top-of-page warning brief and link to a dedicated "Migrating to RBAC v2" section near the bottom of the document instead of front-loading the full cutover checklist into the initial warning. Co-authored-by: c1-squire-dev[bot] --- docs/connector.mdx | 48 +++++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/docs/connector.mdx b/docs/connector.mdx index cbf557fb..c4fea68d 100644 --- a/docs/connector.mdx +++ b/docs/connector.mdx @@ -7,25 +7,7 @@ sidebarTitle: Workato --- -**Legacy Workato roles are being retired at the end of August 2026.** Every Workato workspace must migrate to the new RBAC v2 model (environment roles) before then. Read Workato's [Access Control v2 overview](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/access-control-v2.html) and follow their [migration guide](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/migrate-roles) to migrate your workspace. - -**Before your workspace migrates:** current releases of this connector sync all resource types by default, including **Environment roles** — so Environment roles sync is already enabled even if your workspace is still on the legacy role model. If your workspace hasn't migrated yet, exclude **Environment roles** from sync in the connector's resource type configuration. Enabling it against a legacy workspace fails sync with `failed to list environment roles: 401`, because the `/api/environment_roles` endpoint doesn't exist until after migration. - -**On the same day your workspace migrates to RBAC v2**, complete this cutover in order: - -1. In Workato, update your C1 API client's role with the permissions that only become available after migration: - - **List environment roles** — required - - **Get environment role** — required only if C1 provisions environment role assignments -2. In the connector configuration: - - Enable **Disable custom roles sync**, since custom roles are no longer served from the legacy `/api/roles` endpoint. - - Confirm **Environment roles** sync is enabled (it's on by default — re-enable it now if you excluded it per the note above). - -Getting either side of the cutover wrong fails differently: - -- Enable Environment roles sync too early (before migration) → sync fails with `failed to list environment roles: 401`. -- Leave Environment roles sync disabled too late (after migration) → sync succeeds, but environment role grants are silently dropped — collaborators will appear to have no role assignments. - -Custom roles also move from the legacy `/api/roles` resource to environment roles, a different resource type. The first sync after migration rebuilds all role resources and grants from scratch, so expect a large diff with no retained history — this is expected, not a sync error. +**Legacy Workato roles are being retired at the end of August 2026.** Every Workato workspace must migrate to the new RBAC v2 model (environment roles) before then. See [Migrating to RBAC v2](#migrating-to-rbac-v2) below for the full cutover checklist. ## Provision accounts @@ -104,11 +86,11 @@ Select the following endpoints: | | Environment roles | Get environment role†‡ | `GET /api/environment_roles/:id` | *If you don’t want to use C1 to provision role assignments, you can skip **Update collaborator’s roles** and **Get environment role**. - †**List environment roles** and **Get environment role** are only available after your workspace migrates to RBAC v2 — see the migration notice above for the full cutover sequence. + †**List environment roles** and **Get environment role** are only available after your workspace migrates to RBAC v2 — see [Migrating to RBAC v2](#migrating-to-rbac-v2) for the full cutover sequence. ‡**Get environment role** is required only if you want C1 to provision environment role assignments. - §**The Collaborator roles section** (including **List non-system roles**) only appears in the UI if your workspace uses the legacy roles model. If this section is not visible, your workspace has migrated to RBAC v2 — see the migration notice above, and use Workato's [Role migration API](https://docs.workato.com/workato-api/role-migration.html) to migrate your legacy custom roles to environment roles. + §**The Collaborator roles section** (including **List non-system roles**) only appears in the UI if your workspace uses the legacy roles model. If this section is not visible, your workspace has migrated to RBAC v2 — see [Migrating to RBAC v2](#migrating-to-rbac-v2), and use Workato's [Role migration API](https://docs.workato.com/workato-api/role-migration.html) to migrate your legacy custom roles to environment roles. Save the new role. @@ -349,4 +331,26 @@ Check that the connector data uploaded correctly. In C1, click **Apps**. On the **Done.** Your Workato connector is now pulling access data into C1. - \ No newline at end of file + + +## Migrating to RBAC v2 + +Workato is retiring legacy roles at the end of August 2026. Every workspace must migrate to the new RBAC v2 model (environment roles) before then. Read Workato's [Access Control v2 overview](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/access-control-v2.html) and follow their [migration guide](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/migrate-roles) to migrate your workspace. + +**Before your workspace migrates:** current releases of this connector sync all resource types by default, including **Environment roles** — so Environment roles sync is already enabled even if your workspace is still on the legacy role model. If your workspace hasn't migrated yet, exclude **Environment roles** from sync in the connector's resource type configuration. Enabling it against a legacy workspace fails sync with `failed to list environment roles: 401`, because the `/api/environment_roles` endpoint doesn't exist until after migration. + +**On the same day your workspace migrates to RBAC v2**, complete this cutover in order: + +1. In Workato, update your C1 API client's role with the permissions that only become available after migration: + - **List environment roles** — required + - **Get environment role** — required only if C1 provisions environment role assignments +2. In the connector configuration: + - Enable **Disable custom roles sync**, since custom roles are no longer served from the legacy `/api/roles` endpoint. + - Confirm **Environment roles** sync is enabled (it's on by default — re-enable it now if you excluded it per the note above). + +Getting either side of the cutover wrong fails differently: + +- Enable Environment roles sync too early (before migration) → sync fails with `failed to list environment roles: 401`. +- Leave Environment roles sync disabled too late (after migration) → sync succeeds, but environment role grants are silently dropped — collaborators will appear to have no role assignments. + +Custom roles also move from the legacy `/api/roles` resource to environment roles, a different resource type. The first sync after migration rebuilds all role resources and grants from scratch, so expect a large diff with no retained history — this is expected, not a sync error. \ No newline at end of file From b08dd26f4cf87a6e35aab9becf945f659f67a0d8 Mon Sep 17 00:00:00 2001 From: John Allers Date: Thu, 20 Aug 2026 21:21:53 +0000 Subject: [PATCH 3/5] docs: reword environment roles default-sync note State the default behavior and failure mode plainly instead of framing it as new information existing customers wouldn't already know. Co-authored-by: c1-squire-dev[bot] --- docs/connector.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/connector.mdx b/docs/connector.mdx index c4fea68d..9d54885a 100644 --- a/docs/connector.mdx +++ b/docs/connector.mdx @@ -337,7 +337,7 @@ Check that the connector data uploaded correctly. In C1, click **Apps**. On the Workato is retiring legacy roles at the end of August 2026. Every workspace must migrate to the new RBAC v2 model (environment roles) before then. Read Workato's [Access Control v2 overview](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/access-control-v2.html) and follow their [migration guide](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/migrate-roles) to migrate your workspace. -**Before your workspace migrates:** current releases of this connector sync all resource types by default, including **Environment roles** — so Environment roles sync is already enabled even if your workspace is still on the legacy role model. If your workspace hasn't migrated yet, exclude **Environment roles** from sync in the connector's resource type configuration. Enabling it against a legacy workspace fails sync with `failed to list environment roles: 401`, because the `/api/environment_roles` endpoint doesn't exist until after migration. +**Environment roles** sync requires RBAC v2 and is enabled by default, so it must be excluded from sync until your workspace migrates (otherwise sync fails with `failed to list environment roles: 401`). **On the same day your workspace migrates to RBAC v2**, complete this cutover in order: From d976a86480fa81aea4181b3efe21dd811ed9398f Mon Sep 17 00:00:00 2001 From: John Allers Date: Thu, 20 Aug 2026 21:27:07 +0000 Subject: [PATCH 4/5] docs: soften migration cutover timing wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Say "after your workspace migrates" instead of "on the same day" — the cutover doesn't need to happen same-day, just after migration. Co-authored-by: c1-squire-dev[bot] --- docs/connector.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/connector.mdx b/docs/connector.mdx index 9d54885a..2230fa78 100644 --- a/docs/connector.mdx +++ b/docs/connector.mdx @@ -339,7 +339,7 @@ Workato is retiring legacy roles at the end of August 2026. Every workspace must **Environment roles** sync requires RBAC v2 and is enabled by default, so it must be excluded from sync until your workspace migrates (otherwise sync fails with `failed to list environment roles: 401`). -**On the same day your workspace migrates to RBAC v2**, complete this cutover in order: +**After your workspace migrates to RBAC v2**, complete this cutover in order: 1. In Workato, update your C1 API client's role with the permissions that only become available after migration: - **List environment roles** — required From 17b9c0762ba173a606244255b46faef671c33023 Mon Sep 17 00:00:00 2001 From: Melinda Moreland Date: Thu, 20 Aug 2026 14:55:32 -0700 Subject: [PATCH 5/5] docs: apply connector doc style and structure fixes Co-Authored-By: Claude Sonnet 5 --- docs/connector.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/connector.mdx b/docs/connector.mdx index 2230fa78..5aba50a8 100644 --- a/docs/connector.mdx +++ b/docs/connector.mdx @@ -337,7 +337,7 @@ Check that the connector data uploaded correctly. In C1, click **Apps**. On the Workato is retiring legacy roles at the end of August 2026. Every workspace must migrate to the new RBAC v2 model (environment roles) before then. Read Workato's [Access Control v2 overview](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/access-control-v2.html) and follow their [migration guide](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/migrate-roles) to migrate your workspace. -**Environment roles** sync requires RBAC v2 and is enabled by default, so it must be excluded from sync until your workspace migrates (otherwise sync fails with `failed to list environment roles: 401`). +**Environment roles** sync requires RBAC v2 and is on by default, so exclude it from sync until your workspace migrates (otherwise sync fails with `failed to list environment roles: 401`). **After your workspace migrates to RBAC v2**, complete this cutover in order: @@ -345,12 +345,12 @@ Workato is retiring legacy roles at the end of August 2026. Every workspace must - **List environment roles** — required - **Get environment role** — required only if C1 provisions environment role assignments 2. In the connector configuration: - - Enable **Disable custom roles sync**, since custom roles are no longer served from the legacy `/api/roles` endpoint. - - Confirm **Environment roles** sync is enabled (it's on by default — re-enable it now if you excluded it per the note above). + - Enable **Disable custom roles sync**, since the legacy `/api/roles` endpoint no longer serves custom roles. + - Confirm **Environment roles** sync is on (it is on by default — re-enable it now if you excluded it per the note above). Getting either side of the cutover wrong fails differently: - Enable Environment roles sync too early (before migration) → sync fails with `failed to list environment roles: 401`. -- Leave Environment roles sync disabled too late (after migration) → sync succeeds, but environment role grants are silently dropped — collaborators will appear to have no role assignments. +- Leave Environment roles sync disabled too late (after migration) → sync succeeds, but silently drops environment role grants — collaborators appear to have no role assignments. -Custom roles also move from the legacy `/api/roles` resource to environment roles, a different resource type. The first sync after migration rebuilds all role resources and grants from scratch, so expect a large diff with no retained history — this is expected, not a sync error. \ No newline at end of file +Custom roles also move from the legacy `/api/roles` resource to environment roles, a different resource type. The first sync after migration rebuilds all role resources and grants from scratch, so expect a large diff with no retained history — this is expected, not a sync error.