What’s actually changing
Cloudflare’s own changelog entry gives a real functional gap as its reasoning for the deprecation, not just a naming preference:
“The Account Roles API only returns account-level roles today, and is deprecated in favor of the Permission Groups API”
The Account Roles API’s whole limitation was scope: it only ever surfaced account-level roles, a flat list like “Administrator” or “Billing.” The Permission Groups API, confirmed live at GET /accounts/{account_id}/iam/permission_groups, returns a paginated array of permission groups, each a named group of fine-grained permissions mapped to specific operations against specific resources, a genuinely different and more expressive model.
Structural Comparison Matrix
| Operational Aspect | Account Roles API (deprecated) | Permission Groups API |
|---|---|---|
| Data model | Flat list of account-level role names | Named groups of fine-grained permissions |
| List endpoint | GET /accounts/{account_id}/roles | GET /accounts/{account_id}/iam/permission_groups |
| Filtering | Not documented for this endpoint | Optional name query parameter |
| Granularity | Whole role only | Individual permission-to-operation mappings |
Fix it: migrate the logic, not just the URL
curl -X GET \
"https://api.cloudflare.com/client/v4/accounts/<account_id>/roles" \
-H "Authorization: Bearer <api_token>"curl -X GET \
"https://api.cloudflare.com/client/v4/accounts/<account_id>/iam/permission_groups" \
-H "Authorization: Bearer <api_token>"This is a data-model migration, not a URL swap
Automation that checks if role.name == "Administrator" against the old API
has no direct equivalent field to swap in. The Permission Groups API models
permissions, not a single named role, so gating logic built around role names
needs to be rebuilt around specific permission group membership instead, real
design work, not a one-line change.
Before rewriting anything, pull the actual permission groups available on the account and map which ones correspond to the old role-based checks the automation relied on:
curl -X GET \
"https://api.cloudflare.com/client/v4/accounts/<account_id>/iam/permission_groups?name=Administrator" \
-H "Authorization: Bearer <api_token>"Confirmed version
Sourced from Cloudflare’s official changelog, published 2026-07-21, deprecation effective the same day, corroborated by Cloudflare’s own live API reference for the Permission Groups API endpoint. Browse more posts like this in the Data Automation archive.
