Fine‑Grained Page Restrictions in Confluence: A Practical Guide to Controlling Read/Write Access

Desired Outcome

In Confluence, you often need to limit who can view or edit a page regardless of the space’s global permissions. Page restrictions let you grant or deny read or edit rights to specific users or groups on a single page, a subtree, or inherit from a parent page. This guide walks you through setting up these restrictions, verifying them, and troubleshooting common issues.

Prerequisites

• Confluence Cloud or Server (v7.0+). The REST endpoints differ slightly between Cloud and Server; this guide uses the Cloud API syntax.
• Administrator or space administrator privileges to modify page restrictions.
• Knowledge of the Confluence page ID you want to restrict (e.g., 12345).
• For API usage, a valid OAuth 2.0 token or Basic Auth credentials with the read:confluence and write:confluence scopes.

Step‑by‑Step Procedure

1. Identify the Target Page

Open the page in a browser and note its id from the URL: https://your‑confluence.atlassian.net/wiki/spaces/ABC/pages/12345/Target-Page. The number after the space name is the page ID.

2. Decide Restriction Scope

• Single page only: Restriction applies only to the page.
• Descendants only: Applies to the page and all its child pages.
• Both: Applies to the page and its descendants.

3. Apply Restrictions via the UI

1. Navigate to the target page.
2. Click the ellipsis (⋮) in the top‑right corner and select Restrictions.
3. The Restrictions dialog lists current restrictions. Click Add restriction.
   • Choose Read or Edit from the dropdown.
   • Enter a user or group name (e.g., developers or alice). Confluence will auto‑complete valid entries.
   • Select the scope: Page only, All descendants, or Page and descendants.
   • Click Save.
4. Repeat for additional users/groups or operations as needed.
5. When finished, click Close.

4. Apply Restrictions via the REST API

Using the API is useful for bulk operations or automation. The following example grants the developers group edit access to page 12345 and the user alice read access.

# Update restrictions – replace {pageId} with 12345
curl -X POST \
  "https://your‑confluence.atlassian.net/wiki/rest/api/content/12345/restriction" \
  -H "Authorization: Bearer <YOUR_OAUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "operations": [
    {
      "operation": {
        "id": "2",  // 2 = edit, 1 = read
        "type": "edit"
      },
      "restrictions": {
        "user": [],
        "group": [
          {"name": "developers"}
        ]
      }
    },
    {
      "operation": {
        "id": "1",
        "type": "view"
      },
      "restrictions": {
        "user": [
          {"name": "alice"}
        ],
        "group": []
      }
    }
  ]
}'

Key points:

• Operation IDs: 1 = view, 2 = edit.
• Use group entries for group restrictions and user for individual users.
• Scope is controlled by the restrictionType field if you need to apply to descendants; omitted here defaults to page only.

5. Verify Restrictions

After applying, confirm the restrictions are in place.

• UI Check: Re‑open the Restrictions dialog and verify the list matches the intended users/groups.
• API Check: GET /rest/api/content/12345/restriction/byOperation?operation=edit should return the developers group. For read, use operation=view.
• Functional Test: Log in as a user not listed (e.g., bob) and attempt to open the page. You should see an Access Denied message and the page should not appear in search results.
• Search Test: Use Confluence’s search as the restricted user; the page should be absent.

Recovery Options

• Undo a Restriction via UI: In the Restrictions dialog, click the X next to the restriction and confirm removal.
• Undo via API: Send a DELETE request to /rest/api/content/{id}/restriction/{restrictionId}. Retrieve restrictionId from a prior GET call.
• To revert to the space’s default permissions, clear inheritance: In the Restrictions dialog, click Clear inheritance (if you had inherited restrictions from a parent).
• For bulk removal, script a loop over all page IDs in the space and delete restrictions via API.

Limitations and Practical Checks

Limitation	Practical Check
Inherited restrictions from parent pages can unintentionally block access.	Review the restriction hierarchy in the UI or via GET /rest/api/content/{id}/restriction/byOperation and clear inheritance if needed.
Over‑restricting can lock out legitimate collaborators.	Test in a staging space before applying to production; maintain an all‑users group with read access as a safety net.
API payload errors (400) or insufficient auth (403).	Validate JSON schema against Atlassian’s API reference; use a tool like Postman to test with proper OAuth scopes.
Restrictions are not inherited by new child pages automatically.	When creating a new page under a restricted parent, manually apply the same restrictions or enable “Apply restrictions to all descendants” at the parent level.

Conclusion

Page restrictions give Confluence admins precise control over who can see or edit content, independent of space or global permissions. By following the UI or API steps above, verifying with both UI and REST calls, and planning for recovery, you can safely enforce confidentiality or collaboration constraints on a per‑page basis.