← All breaking-change reports

Cloudflare deprecation: Cloudflare Fundamentals - Account Role API deprecated

cloudflare · deprecation · 2026-07-21 · upstream source

What changed

Account Roles API replaced by the Permission Groups API; response schema differs and role IDs must be remapped

From the upstream announcement:

The Account Roles API is deprecated and is being replaced by the Permission Groups API . An end of life date has not yet been established. What you need to do Review the Permission Groups API documentation; the response schema differs from the legacy Roles response. Highlights Integrations migrating to the Permission Groups API must obtain Permission Group IDs from that API and use them in the Account Members API policies request shape. Integrations that persist legacy Role IDs will need to remap their assignments. The legacy Role response includes a top-level description and a permissions object keyed by resource type with edit/read flags. The PermissionGroup response replaces those with a meta object containing label and scopes . Individual permissions are not returned as part of the permission group. The new API supports the API Token authorization scheme. The legacy Email + API Key a […]

Who is affected

Two-layer mend with a documented field map.

To find out whether your repo is hit — file and line number, no code leaving your machine:

npx mendapi scan --repo .

How to fix it

mendapi ships a deterministic migration pack for this change (cloudflare-account-roles-to-permission-groups). Preview the patch locally (dry-run is the default; nothing is modified without --apply):

npx mendapi fix --repo . --migration cloudflare-account-roles-to-permission-groups

The pack is idempotent, gold-regression tested, and safe on partially migrated code.

What the migration does:

Two-layer mend with a documented field map. Endpoint layer: list/read calls against the account roles routes move to the permission groups routes, and Account Members policy payloads switch from role IDs to permission group IDs. Schema layer at read sites: role.description becomes group.meta.label, and consumers of the per-resource permissions edit/read flags must drop that projection because individual permissions are not returned — scope-level checks against group.meta.scopes are the replacement. The read-site field remap and URL swap are mechanical; the ID remapping of persisted role assignments needs a one-time data migration keyed on the new list response, which the draft flags as an operational step rather than a codemod. No hard deadline exists yet, so the mend can ship as a prepared draft.

Before:

const roles = await cf(`/accounts/${acct}/roles`);
const admin = roles.result.find((r) => r.description === 'Administrator');

After:

const groups = await cf(`/accounts/${acct}/iam/permission_groups`);
const admin = groups.result.find((g) => g.meta.label === 'Administrator');

Replacement data source: Permission Groups API returns the successor records; labels/scopes live under the meta object of each permission group

Detected and tracked by mendapi — Dependabot for every API you depend on. Scans run locally; your code never leaves your machine.

Related

Pre-release. Change data is recorded from upstream provider releases, changelogs and OpenAPI spec diffs; every article links its source.