Confluence Cloud is tightening the restrictions API: the scripts that will break, and the V2 move

Sami Shaik

Two changes landed on the Confluence Cloud developer changelog within a day of each other, and together they change how restriction automation behaves on your site. One is new API surface. The other is a behaviour change to the API you are probably already using, and it is rolling out tenant by tenant right now. If you have a script, an automation or an app that sets page restrictions, read this before it fails quietly.

What changed

14 October: V2 permissions endpoints. The changelog entry adds, for pages, blog posts, databases, whiteboards and folders:

• GET and PUT /wiki/api/v2/{content-type}/{id}/restriction-state
• GET, POST, PUT and DELETE /wiki/api/v2/{content-type}/{id}/permissions

Atlassian’s wording: “we recommend using these new v2 endpoints” for new integrations and for migrating off the V1 content restrictions API.

15 October: V1 behaviour change, progressive rollout, in progress. On the V1 content restriction endpoints (/wiki/rest/api/content/{id}/restriction and its by-operation children), a principal can now hold either the read restriction alone, or read and update together. Two consequences, in the changelog’s own terms:

1. A request that removes only the read restriction from a principal who holds both is rejected.
2. To put content into an edit-restricted state for those principals, you remove all read restrictions.

The required action is stated plainly: when you grant update, include read for the same principal, and treat read as a prerequisite for update in any removal logic.

Why this matters more than it looks

Under the old model you could, through the API, create a principal with edit rights and no explicit view rights. The UI never let you do that, but scripts did, usually by accident: a migration tool copying update restrictions without read, a provisioning script that granted edit to a group and left view inherited, a cleanup job that stripped read entries to “open up” a page. Those pages have been living in a state the product never intended. The V1 change stops new ones being created and, more importantly, starts rejecting the calls that used to create them.

A rejected call is good news when a human is watching and bad news when a script runs at 02:00 and nobody reads the log. Because the rollout is per tenant, your sandbox and your production site may behave differently this week.

The three places to look

1. Scripts that write restrictions. Anything calling PUT /wiki/rest/api/content/{id}/restriction (which replaces the whole set) or the by-operation POST and DELETE endpoints. Search your repositories for restriction and byOperation. The failing pattern is any removal that touches read alone, and any grant of update without a matching read.
2. Automation for Confluence rules that set restrictions on created pages. Open the rule, check whether it grants edit without view. (I have not reproduced a failure through Automation itself; test one rule in a sandbox before assuming it is unaffected.)
3. Marketplace apps that manage permissions. You cannot read their code, but you can read their behaviour: after the rollout reaches you, create a test page, let the app apply its restrictions, then call GET /wiki/api/v2/pages/{id}/permissions and look at what each principal holds.

What the V2 model gives you

The V2 design encodes the rule instead of trusting the caller. From the V2 reference:

• Restriction state is one enum, not a set of operations: OPEN, EDIT_RESTRICTED (viewing open, editing limited to granted principals) or VIEW_RESTRICTED (both limited). It describes direct restrictions only; inherited ones are not represented.
• A principal holds one permission, read or update. Adding read to someone who has update downgrades them; adding update upgrades them. If one request contains both, update wins. Reasserting an existing permission is idempotent.
• POST merges, PUT replaces. POST /permissions adds or replaces permissions for the principals you name and leaves the others alone; PUT replaces the whole set. That distinction is where most V1 scripts went wrong.
• A lockout guard. Both the restriction-state and permissions writes take allow-self-lockout, default false: the call is rejected if it would remove the caller’s own edit access. Set it to true only when you mean it.
• Scopes: read:page:confluence and write:page:confluence for pages (the other content types take their own).

A migration path that does not break anything on the way

1. Inventory first. For each restricted page your scripts manage, call GET /restriction-state and GET /permissions on V2 and record the result. This is read-only and safe today.
2. Find the illegal states. Any principal with update and no read under V1 is a page the new rules will treat differently. The V2 permissions read shows it as a single update entry, which is fine in V2; the risk is only in V1 scripts that will next try to modify it.
3. Rewrite the writers to V2, using POST /permissions for incremental changes and PUT /restriction-state for the open or restricted switch. Keep allow-self-lockout at its default.
4. Run the old and new side by side in a sandbox on the same test pages, and diff the GET /permissions output.
5. Retire the V1 calls, and tell whoever owns the service account.

Checklist

• Search code and automation rules for restriction and byOperation.
• Add read wherever you grant update; never remove read alone.
• Read every managed page through V2 GET /permissions once, before changing anything.
• Move writers to V2: POST /permissions to merge, PUT /restriction-state to switch state.
• Leave allow-self-lockout false.
• Test on a sandbox, then production, because the rollout reaches them at different times.

I have not yet hit the rejection on a V1 call myself: as of 21 October, a PUT to /restriction with an update restriction and no read restriction still returned 200 on a sandbox I administer, so the rollout had not reached it. If you have hit it, say which call and which error body you got, and I will add it here with credit.

Verified 20 October 2026 against the Confluence Cloud developer changelog (entries of 14 and 15 October), the Confluence Cloud REST API v2 reference (Content Permissions) and the REST API v1 Content restrictions reference. Confluence Cloud only; Data Center restrictions are a different API.