Confluence Forge Page Deletion: Scope, Identity & Cascades

Confluence Forge page deletion is controlled by three distinct mechanisms: the deletion scope (which pages are affected), the identity of the deleting user (and their permissions), and cascade behavior (what happens to child pages and associated content). Understanding these three factors is essential for anyone managing a Forge app that manipulates Confluence pages, as misconfiguring them can lead to accidental data loss or permission errors.

Background: What Is Forge and Why Deletion Matters

Forge is Atlassian’s cloud development platform for building apps that run on Confluence, Jira, and other Atlassian products. Unlike older Connect apps, Forge apps are hosted on Atlassian’s infrastructure and use a declarative security model. When a Forge app needs to delete a Confluence page, it uses the Forge Confluence API, which exposes a deletePage function. The behavior of this function is not always intuitive, especially when dealing with page hierarchies and permissions.

Deletion is a destructive operation, and Confluence enforces strict rules to prevent accidental removal of content. Forge apps must explicitly declare the scopes they need (e.g., read:page:confluence, write:page:confluence) and the deletion operation requires the write:page:confluence scope. However, having the scope is not enough; the user who triggers the deletion must also have the appropriate Confluence permissions on the page.

How Deletion Scope Works in Forge

The scope of a deletion operation in Forge is determined by the API call you make. The deletePage function takes a single page ID and deletes that specific page. There is no built-in “delete subtree” function in the Forge API. To delete a page and its children, you must recursively fetch child pages and delete them individually.

Here is a typical pattern for deleting a page and its descendants:

1. Fetch the page’s children using the getPageChildren function.
2. For each child, recursively call the same deletion routine.
3. Delete the child pages first, then the parent page.

Important: Confluence does not allow deleting a page that has children unless you explicitly delete the children first. If you attempt to delete a parent page with existing children, the API returns an error. This is a safety mechanism to prevent accidental cascade deletions.

Identity: Who Is Performing the Deletion?

The identity of the user performing the deletion matters because Confluence permissions are user-based. When a Forge app calls deletePage, it does so on behalf of the user who is currently using the app (the “calling user”). The app cannot delete a page if that user does not have the “Delete” permission on the page.

There is also the concept of an “app user” (or service account). In some Forge APIs, you can perform operations as the app itself, rather than as a specific user. However, for Confluence page deletion, the API requires a user context. This means the app must be invoked from a Confluence page or a UI module where the user is authenticated, and the deletion is attributed to that user.

If the calling user has permission to delete the page, the deletion proceeds. If not, the API returns a 403 Forbidden error. It is important to handle this error gracefully in your app, as it can occur even if the app has the correct scopes.

Cascades: What Happens to Child Pages and Content?

Confluence does not automatically cascade deletions. When you delete a page, only that page is deleted. Child pages remain in the space, but they are “orphaned” – they no longer have a parent. In the Confluence UI, orphaned pages are still accessible, but they appear in a special “Orphaned Pages” view. They are not deleted automatically.

For a Forge app, this means that if you delete only a parent page, you must decide what to do with its children. The safest approach is to delete children first, then the parent. Alternatively, you could reparent the children to another page before deleting the parent. The Forge API does not provide a “cascade delete” option, so you must implement this logic yourself.

Also note that deleting a page does not delete its attachments or comments. These are also left as orphaned content. If you need to remove all traces of a page, you must delete attachments and comments separately using the respective API functions.

How to Choose the Right Deletion Strategy

Choosing the right deletion strategy depends on your use case:

• Deleting a single page – Use deletePage directly. Ensure the page has no children, or handle the error.
• Deleting a page and all its descendants – Implement a recursive deletion function that traverses the page tree. This is the most common pattern for bulk cleanup.
• Moving children before deletion – If you want to preserve child pages, use the updatePage function to change the parent ID before deleting the original parent.
• Deleting a page and its attachments/comments – Fetch and delete attachments and comments before deleting the page itself.

Always test your deletion logic in a staging environment before deploying to production, as accidental deletions are hard to undo.

Common Problems and Misconceptions

One common misconception is that the Forge API’s deletePage will automatically delete child pages. It does not. This is a frequent source of bugs in Forge apps.

Another issue is permission errors. Even if the app has the correct scopes, the calling user might not have the “Delete” permission on the page. This often happens when a page is restricted or when the user is not a space admin. To avoid this, check permissions before attempting deletion, or handle the 403 error gracefully.

Also, be aware of the difference between “delete” and “archive”. Confluence allows archiving pages, which removes them from the active tree but retains them for later retrieval. The Forge API does not have an “archive” function; you would need to use the Confluence REST API directly for that.

Comparisons: Forge vs. Confluence REST API

The Forge API is designed for use within Forge apps and abstracts away some of the complexity of the Confluence REST API. However, the REST API offers more flexibility:

• REST API – You can call DELETE /rest/api/content/{id} to delete a page. It also does not cascade, but you can use query parameters to control behavior (e.g., ?status=trashed to move to trash instead of permanent deletion).
• Forge API – Simpler, but limited to the functions provided. For example, you cannot move a page to the trash via Forge; you can only permanently delete it.

If you need advanced functionality like moving pages to trash or restoring them, you may need to use the REST API from your Forge app via fetch or the api function.

Safety and Best Practices

Deleting pages is irreversible in Forge – there is no trash or undo. Therefore, consider the following best practices:

• Always confirm with the user before performing a deletion.
• Log all deletion actions with page IDs and user IDs for audit purposes.
• Implement a soft-delete mechanism (e.g., mark a page as “deleted” in a custom field) instead of hard deletion, if possible.
• Use the read:page:confluence scope to verify the page exists and is accessible before deletion.
• Handle errors gracefully, especially 403 and 404 errors.

By following these practices, you can avoid accidental data loss and ensure your Forge app behaves predictably.

Frequently Asked Questions

Does deleting a parent page in Forge delete its children?

No. The Forge API’s deletePage function only deletes the specified page. Child pages are left orphaned. You must delete them manually or reparent them.

Can I restore a page deleted via Forge?

No. Forge deletion is permanent and does not move pages to the trash. There is no built-in restore function. You would need to have a backup or a custom restore mechanism.

What scopes do I need to delete a page?

You need the write:page:confluence scope. Additionally, the calling user must have the “Delete” permission on the page in Confluence.

Why do I get a 403 error when deleting a page?

This usually means the calling user does not have permission to delete the page. Check the page’s restrictions and the user’s space permissions.

How do I delete a page and all its attachments?

You must first fetch the page’s attachments using getPageAttachments and delete each one, then delete the page. There is no single call to do both.

Related

• Claude Cowork Alternatives: Tools for AI Workflows
• No Man’s Sky vs Starfield: Planet Exploration Compared
• SNES Mini Games Hack: What It Does and How It Works