Last updated May 31, 2022

Rate this page:

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 nameSummaryDescription
write:confluence-contentWrite Confluence contentPermits the creation of pages, blogs, comments, and questions.
read:confluence-space.summaryRead Confluence space summaryRead a summary of space information without expansions.
write:confluence-spaceManage Confluence space detailsCreate, update, and delete space information.
write:confluence-fileUpload Confluence attachmentsUpload attachments.
read:confluence-propsRead Confluence content propertiesRead content properties.
write:confluence-propsWrite Confluence content propertiesWrite content properties.
manage:confluence-configurationManage Confluence global settingsManage global settings.
read:confluence-content.allRead 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.summaryRead 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:confluenceSearch 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.permissionRead content permission in ConfluenceView content permission in Confluence.
read:confluence-userRead userView user information in Confluence that you have access to, including usernames, email addresses, and profile pictures.
read:confluence-groupsRead user groupsPermits retrieval of user groups.
write:confluence-groupsCreate, remove and update user groupsPermits creation, removal, and update of user groups.
readonly:content.attachment:confluenceDownload content attachmentsDownload 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 nameTitleDescription
read:content:confluenceView contentView content, including pages, blogposts, custom content, attachments, comments, and content templates.
read:content-details:confluenceView content detailsView details regarding content and its associated properties.
write:content:confluenceCreate and update contentCreate and update content and its associated properties.
delete:content:confluenceDelete contentDelete content.
read:space-details:confluenceView space detailsView details regarding spaces and their associated properties.
read:analytics.content:confluenceView analytics for contentView analytics for content. Note that this does not provide access to the content itself.
read:audit-log:confluenceView audit recordsView and export audit records for Confluence events.
write:audit-log:confluenceCreate audit recordsCreate records in the audit log.
read:configuration:confluenceView Confluence settingsView Confluence settings, themes, and system information.
write:configuration:confluenceUpdate Confluence settingsUpdate Confluence settings, including global look and feel.
read:page:confluenceView pagesView page content.
write:page:confluenceCreate and update pagesCreate and update pages.
delete:page:confluenceDelete pagesDelete pages.
read:blogpost:confluenceView blogpostsView blogpost content.
write:blogpost:confluenceCreate and update blogpostsCreate and update blogposts.
delete:blogpost:confluenceDelete blogpostsDelete blogposts.
read:custom-content:confluenceView custom contentView custom content.
write:custom-content:confluenceCreate and update custom contentCreate and update custom content.
delete:custom-content:confluenceDelete custom contentDelete custom content.
read:attachment:confluenceView and download content attachmentsView and download content attachments.
write:attachment:confluenceCreate and update content attachmentsCreate and update content attachments.
delete:attachment:confluenceDelete content attachmentsDelete content attachments.
read:comment:confluenceView commentsView comments on content.
write:comment:confluenceCreate and update commentsCreate and update comments on content.
delete:comment:confluenceDelete commentsDelete comments on content.
read:template:confluenceView content templatesView content templates.
write:template:confluenceCreate, update, and delete content templatesCreate, update, and delete content templates.
read:label:confluenceView labelsView labels associated with content or spaces.
write:label:confluenceAdd and remove labelsAdd and remove labels associated with content or spaces.
read:content.permission:confluenceCheck content permissionsCheck if a user or group can perform an operation on the specified content.
read:content.property:confluenceView content propertiesView properties associated with content.
write:content.property:confluenceCreate, update, and delete content propertiesCreate, update, and delete properties associated with content.
read:content.restriction:confluenceView content restrictionsView the restrictions on content.
write:content.restriction:confluenceUpdate content restrictionsUpdate the restrictions on content.
read:content.metadata:confluenceView content summariesView information about content. Note that this does not provide access to the content itself.
read:watcher:confluenceView watchers of content, spaces, or labelsView the watchers associated with content, spaces, or labels.
write:watcher:confluenceAdd and remove watchers of content, spaces, or labelsAdd and remove the watchers associated with content, spaces, or labels.
read:group:confluenceView groupsView details about groups.
write:group:confluenceCreate, update, and delete groupsCreate, update, and delete groups.
read:inlinetask:confluenceView tasksSearch and view inline tasks.
write:inlinetask:confluenceMark inline task statusMark inline tasks as complete or incomplete.
read:relation:confluenceView entity relationshipsView relationships between two entities.
write:relation:confluenceCreate and update entity relationshipsCreate and update relationships between two entities.
read:space:confluenceView spacesView space details.
write:space:confluenceCreate and update spacesCreate and update spaces.
delete:space:confluenceDelete spacesDelete spaces.
read:space.permission:confluenceView space permissionsView space permissions.
write:space.permission:confluenceUpdate space permissionsUpdate space permissions.
read:space.property:confluenceView space propertiesView properties associated with spaces.
write:space.property:confluenceCreate, update, and delete space propertiesCreate, update, and delete properties associated with spaces.
read:user.property:confluenceView user propertiesView properties associated with user.
write:user.property:confluenceCreate, update, and delete user propertiesCreate, update, and delete properties associated with user.
read:space.setting:confluenceView space settingsView space settings and themes.
write:space.setting:confluenceUpdate space settingsUpdate space settings and themes.
read:user:confluenceView user detailsView user details.

Rate this page: