Last updated Nov 21, 2024

Confluence scopes for OAuth 2.0 (3LO) and Forge apps

Scopes enable an app to request a level of access to an Atlassian product.

Confluence permissions also control access to data and aren't overridden by scopes. For example, if a user does not have permission to update content then the update won't be able to access content even if the app has the write:confluence-content scope.
The scopes may provide the potential to access beta or non-public APIs that are later changed or removed from the Atlassian product. The inclusion of the API endpoint in a scope doesn't imply that the product makes this endpoint public. Read the Confluence Cloud REST API documentation for details.
Some scopes automatically imply that the app is granted other scopes.

Setting your app's scopes

When choosing your scopes, the recommendation is to use classic scopes.

Scopes limit

It's recommended that you use less than 50 scopes in an application. When adding scopes in the developer console, a count of the scopes added to your app is displayed. If you are approaching 50 scopes, review your use of scopes and ensure you're using classic scopes to the maximum extent possible and remove any unnecessary granular scopes.

Forge apps

The easiest way to set your app's scopes is to:

Update to the latest forge-cli packages.
Run forge lint --fix to add the scopes to the manifest.

This process does not remove any redundant scopes from the manifest file, and these scopes need to be removed manually.

If you want to set the scopes manually, you need to:

Review your app to determine all of the operations used.
Consult the Confluence Cloud REST API documentation to determine the scope needed for each operation and create a list of scopes.
Add the scopes required to the app's manifest file while remembering to remove any deprecated scopes.

OAuth 2.0 apps

For OAuth 2.0 apps, you need to:

Review your app to determine all of the operations used.
Consult the Confluence Cloud REST API documentation to determine the scope needed for each operation and create a list of scopes.
Update the scopes required in the developer console.

Scopes

The scopes below are for apps using OAuth 2.0 authorization code grants (3LO) for authorization and Forge apps. The title and description are displayed to the user on the consent screen during the authorization flow.

Scopes for Atlassian Connect are different. See Scopes for Connect apps to learn more.

Classic scopes

Where available, the recommendation is to use classic scopes.

Scope name	Summary	Description
`write:confluence-content`	Write Confluence content	Permits the creation of pages, blogs, comments, and questions.
`read:confluence-space.summary`	Read Confluence space summary	Read a summary of space information without expansions.
`write:confluence-space`	Manage Confluence space details	Create, update, and delete space information.
`write:confluence-file`	Upload Confluence attachments	Upload attachments.
`read:confluence-props`	Read Confluence content properties	Read content properties.
`write:confluence-props`	Write Confluence content properties	Write content properties.
`manage:confluence-configuration`	Manage Confluence global settings	Manage global settings.
`read:confluence-content.all`	Read Confluence detailed content	Read all content, including content body (expansions permitted). Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
`read:confluence-content.summary`	Read Confluence content summary	Read a summary of the content, which is the content without expansions. Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
`search:confluence`	Search Confluence content and space summaries	Search Confluence. Note, APIs using this scope may also return data allowed by read:confluence-space.summary and read:confluence-content.summary. However, this scope is not a substitute for read:confluence-space.summary or read:confluence-content.summary.
`read:confluence-content.permission`	Read content permission in Confluence	View content permission in Confluence.
`read:confluence-user`	Read user	View user information in Confluence that you have access to, including usernames, email addresses, and profile pictures.
`read:confluence-groups`	Read user groups	Permits retrieval of user groups.
`write:confluence-groups`	Create, remove and update user groups	Permits creation, removal, and update of user groups.
`readonly:content.attachment:confluence`	Download content attachments	Download attachments of a Confluence page or blogpost that you have access to.

Granular scopes

Use these scopes only when you can't use classic scopes.

Scope name	Title	Description
`read:content:confluence`	View content	View content, including pages, blogposts, custom content, attachments, comments, and content templates.
`read:content-details:confluence`	View content details	View details regarding content and its associated properties.
`write:content:confluence`	Create and update content	Create and update content and its associated properties.
`delete:content:confluence`	Delete content	Delete content.
`read:space-details:confluence`	View space details	View details regarding spaces and their associated properties.
`read:analytics.content:confluence`	View analytics for content	View analytics for content. Note that this does not provide access to the content itself.
`read:audit-log:confluence`	View audit records	View and export audit records for Confluence events.
`write:audit-log:confluence`	Create audit records	Create records in the audit log.
`read:configuration:confluence`	View Confluence settings	View Confluence settings, themes, and system information.
`write:configuration:confluence`	Update Confluence settings	Update Confluence settings, including global look and feel.
`read:page:confluence`	View pages	View page content.
`write:page:confluence`	Create and update pages	Create and update pages.
`delete:page:confluence`	Delete pages	Delete pages.
`read:blogpost:confluence`	View blogposts	View blogpost content.
`write:blogpost:confluence`	Create and update blogposts	Create and update blogposts.
`delete:blogpost:confluence`	Delete blogposts	Delete blogposts.
`read:custom-content:confluence`	View custom content	View custom content.
`write:custom-content:confluence`	Create and update custom content	Create and update custom content.
`delete:custom-content:confluence`	Delete custom content	Delete custom content.
`read:attachment:confluence`	View and download content attachments	View and download content attachments.
`write:attachment:confluence`	Create and update content attachments	Create and update content attachments.
`delete:attachment:confluence`	Delete content attachments	Delete content attachments.
`read:comment:confluence`	View comments	View comments on content.
`write:comment:confluence`	Create and update comments	Create and update comments on content.
`delete:comment:confluence`	Delete comments	Delete comments on content.
`read:template:confluence`	View content templates	View content templates.
`write:template:confluence`	Create, update, and delete content templates	Create, update, and delete content templates.
`read:label:confluence`	View labels	View labels associated with content or spaces.
`write:label:confluence`	Add and remove labels	Add and remove labels associated with content or spaces.
`read:content.permission:confluence`	Check content permissions	Check if a user or group can perform an operation on the specified content.
`read:content.property:confluence`	View content properties	View properties associated with content.
`write:content.property:confluence`	Create, update, and delete content properties	Create, update, and delete properties associated with content.
`read:content.restriction:confluence`	View content restrictions	View the restrictions on content.
`write:content.restriction:confluence`	Update content restrictions	Update the restrictions on content.
`read:content.metadata:confluence`	View content summaries	View information about content. Note that this does not provide access to the content itself.
`read:watcher:confluence`	View watchers of content, spaces, or labels	View the watchers associated with content, spaces, or labels.
`write:watcher:confluence`	Add and remove watchers of content, spaces, or labels	Add and remove the watchers associated with content, spaces, or labels.
`read:group:confluence`	View groups	View details about groups.
`write:group:confluence`	Create, update, and delete groups	Create, update, and delete groups.
`read:inlinetask:confluence`	View tasks	Search and view inline tasks.
`write:inlinetask:confluence`	Mark inline task status	Mark inline tasks as complete or incomplete.
`read:relation:confluence`	View entity relationships	View relationships between two entities.
`write:relation:confluence`	Create and update entity relationships	Create and update relationships between two entities.
`read:space:confluence`	View spaces	View space details.
`write:space:confluence`	Create and update spaces	Create and update spaces.
`delete:space:confluence`	Delete spaces	Delete spaces.
`read:space.permission:confluence`	View space permissions	View space permissions.
`write:space.permission:confluence`	Update space permissions	Update space permissions.
`read:space.property:confluence`	View space properties	View properties associated with spaces.
`write:space.property:confluence`	Create, update, and delete space properties	Create, update, and delete properties associated with spaces.
`read:user.property:confluence`	View user properties	View properties associated with user.
`write:user.property:confluence`	Create, update, and delete user properties	Create, update, and delete properties associated with user.
`read:space.setting:confluence`	View space settings	View space settings and themes.
`write:space.setting:confluence`	Update space settings	Update space settings and themes.
`read:user:confluence`	View user details	View user details.
`read:task:confluence`	View tasks	View Confluence tasks.
`write:task:confluence`	Update tasks	Update Confluence tasks.
`read:email-address:confluence`	Read email addresses	View email addresses of all users regardless of user’s profile visibility settings.