Cloudflare's Account Roles API Is Deprecated! Permission Management Moves to the Permission Groups API

Hi, I'm Shii-chan! Today I've got a piece of Cloudflare news that looks small but is actually worth paying attention to. The account permission management API is changing!

Cloudflare Changelog developers.cloudflare.com

What was announced?

According to Cloudflare's Changelog, the Account Roles API used to manage account permissions has been deprecated. It's being replaced by the Permission Groups API. An end-of-life date hasn't been set yet, so the old API isn't disappearing today, but this is a heads-up that you should start preparing for the change.

The story so far

Until now, Cloudflare used a system called Roles to describe what operations were allowed within an account. The Role response included a top-level description plus a permissions object keyed by resource type, with edit and read flags for each. Combined with the Account Members API, this was the standard way to manage which Role a member was assigned.

What changes

With the move to the Permission Groups API, the unit of permission management shifts from Roles to Permission Groups. When you build policies for the Account Members API, you now need to use Permission Group IDs obtained from the Permission Groups API.

If your integration has been persisting legacy Role IDs, those will need to be remapped to Permission Group IDs — they won't work as-is anymore. In other words, if you have automation, scripts, or tools (like Terraform configs or custom admin panels) that manage Cloudflare account roles, you'll likely need to update your code.

Dive Deep

Looking closely at the response shapes, the difference is clear.

• Legacy Role response: a top-level description, plus a permissions object keyed by resource type with edit/read flags
• New PermissionGroup response: a meta object containing label and scopes

Importantly, individual permissions are no longer returned as part of the permission group response. So if you need to know exactly which permissions are tied to a group, you can't just read a permissions field the old way — you'll need to follow the schema documented for the Permission Groups API.

Authentication is changing too, in a smaller way. The new Permission Groups API supports the API Token authorization scheme. The legacy Email + API Key authorization scheme is still provided for backwards compatibility, so you won't be forced to switch your auth method right away — that's a bit of a relief.

Wrap-up

• Cloudflare's Account Roles API is deprecated, and migration to the Permission Groups API has begun
• No end-of-life date yet, but it's smart to prepare early
• The response schema is changing: description + permissions (edit/read) becomes meta (label, scopes), and individual permissions are no longer returned
• Integrations that persist legacy Role IDs need to remap them to Permission Group IDs
• Authentication still supports both API Token and Email + API Key

This news is especially relevant if you're automating Cloudflare account permission management or building tools on top of the Account Members API!