Last updated May 8, 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.

  • Jira permissions also control access to data and aren't overridden by scopes. For example, if a user does not have the Browse projects permission then the Get project operation won't be able to access project data even if the app has the manage:jira-project and other required scopes.
  • 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 Jira 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

All applications are limited to a maximum of 50 scopes. When adding scopes in the developer console, you receive a warning when you reach this limit. If you reach the limit, 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 Jira Cloud platform 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 Jira Cloud platform 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

These scopes 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 know more.

Classic scopes

Where available, the recommendation is to use these scopes.

Scope nameSummaryDescription
read:jira-userView user profilesView user information in Jira that the user has access to, including usernames, email addresses, and avatars.
read:jira-workView Jira issue dataRead Jira project and issue data, search for issues and objects associated with issues like attachments and worklogs.
write:jira-workCreate and manage issuesCreate and edit issues in Jira, post comments as the user, create worklogs, and delete issues.
manage:jira-projectManage project settingsCreate and edit project settings and create new project-level objects (for example, versions and components).
manage:jira-configurationManage Jira global settingsTake Jira administration actions (for example, create projects and custom fields, view workflows, and manage issue link types).
manage:jira-webhookManage Jira webhooksFetch, register, refresh, and delete dynamically declared Jira webhooks.

Granular scopes

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

Scope nameTitleDescription
read:application-role:jiraView application rolesView application roles.
read:audit-log:jiraView audit logsView audit logs.
read:avatar:jiraView avatarsView system and custom avatars.
write:avatar:jiraCreate and update avatarsCreate and update system and custom avatars.
delete:avatar:jiraDelete avatarsDelete system and custom avatars.
read:project.avatar:jiraRead project avatarsRead project avatars.
write:project.avatar:jiraCreate and update project avatarsCreate and update project avatars.
delete:project.avatar:jiraDelete project avatarsDelete project avatars.
read:dashboard:jiraView dashboardsView dashboards.
write:dashboard:jiraCreate and update dashboardsCreate and update dashboards.
delete:dashboard:jiraDelete dashboardsDelete dashboards.
read:dashboard.property:jiraView dashboard propertiesView dashboard properties.
write:dashboard.property:jiraCreate and update dashboard propertiesCreate and update dashboard properties.
delete:dashboard.property:jiraDelete dashboard propertiesDelete dashboard properties.
read:filter:jiraView filtersView filters.
write:filter:jiraCreate and update filtersCreate and update filters.
delete:filter:jiraDelete filtersDelete filters.
read:filter.column:jiraView filter columnsView filter columns.
write:filter.column:jiraCreate and update filter columnsCreate and update filter columns.
delete:filter.column:jiraDelete filter columnsDelete filter columns.
read:filter.default-share-scope:jiraView filter default share scopesView filter default share scopes.
write:filter.default-share-scope:jiraCreate and update filter default share scopesCreate and update filter default share scopes.
read:group:jiraView groupsView user groups.
write:group:jiraCreate and update groupsCreate and update user groups.
delete:group:jiraDelete groupsDelete user groups.
read:license:jiraView licensesView licenses.
read:issue:jiraView issuesView issues.
write:issue:jiraCreate and update issuesCreate and update issues.
delete:issue:jiraDelete issuesDelete issues.
read:issue-meta:jiraView issue metaView issue meta.
send:notification:jiraSend notificationsSend notifications.
read:attachment:jiraView attachmentsView issue attachments.
write:attachment:jiraCreate and update attachmentsCreate and update issue attachments.
delete:attachment:jiraDelete attachmentsDelete issue attachments.
read:comment:jiraView commentsView issue comments.
write:comment:jiraCreate and update commentsCreate and update issue comments.
delete:comment:jiraDelete commentsDelete issue comments.
read:comment.property:jiraView comment propertiesView issue comment properties.
write:comment.property:jiraCreate and update comment propertiesCreate and update issue comment properties.
delete:comment.property:jiraDelete comment propertiesDelete issue comment properties.
read:field:jiraView fieldsView fields.
write:field:jiraCreate and update fieldsCreate and update fields.
delete:field:jiraDelete fieldsDelete fields.
read:field.default-value:jiraView field default valuesView field default values.
write:field.default-value:jiraCreate and update field default valuesCreate and update field default values.
read:field.option:jiraView field optionsView field options.
write:field.option:jiraCreate and update field optionsCreate and update field options.
delete:field.option:jiraDelete field optionsDelete field options.
read:field-configuration-scheme:jiraView field configuration schemesView field configuration schemes.
write:field-configuration-scheme:jiraCreate and update field configuration schemesCreate and update field configuration schemes.
delete:field-configuration-scheme:jiraDelete field configurationsDelete field configuration schemes.
read:custom-field-contextual-configuration:jiraRead custom field contextual configurationsRead custom field contextual configurations.
write:custom-field-contextual-configuration:jiraSave custom field contextual configurationsSave custom field contextual configurations.
read:field-configuration:jiraRead field configurationsRead field configurations.
write:field-configuration:jiraSave field configurationsSave field configurations.
delete:field-configuration:jiraDelete field configurationsDelete field configurations.
read:field.options:jiraRead field optionsRead field options.
read:issue-link:jiraView issue linksView issue links.
write:issue-link:jiraCreate and update issue linksCreate and update issue links.
delete:issue-link:jiraDelete issue linksDelete issue links.
read:issue-link-type:jiraView issue link typesView issue link types.
write:issue-link-type:jiraCreate and update issue link typesCreate and update issue link types.
delete:issue-link-type:jiraDelete issue link typesDelete issue link types.
read:notification-scheme:jiraView notification schemesView notification schemes.
read:priority:jiraView prioritiesView priorities.
read:issue.property:jiraView issue propertiesView issue properties.
write:issue.property:jiraCreate and update issue propertiesCreate and update issue properties.
delete:issue.property:jiraDelete issue propertiesDelete issue properties.
read:issue.remote-link:jiraView issue remote linksView issue remote links.
write:issue.remote-link:jiraCreate and update issue remote linksCreate and update issue remote links.
delete:issue.remote-link:jiraDelete issue remote linksDelete issue remote links.
read:resolution:jiraView resolutionsView resolutions.
read:issue-details:jiraView issue detailsView issue details.
read:issue-security-scheme:jiraView issue security schemesView issue security schemes.
read:issue-type:jiraView issue typesView issue types.
write:issue-type:jiraCreate and update issue typesCreate and update issue types.
delete:issue-type:jiraDelete issue typesDelete issue types.
read:issue-type-scheme:jiraView issue type schemesView issue type schemes.
write:issue-type-scheme:jiraCreate and update issue type schemesCreate and update issue type schemes.
delete:issue-type-scheme:jiraDelete issue type schemesDelete issue type schemes.
read:issue-type-screen-scheme:jiraView issue type screen schemesView issue type screen schemes.
write:issue-type-screen-scheme:jiraCreate and update issue type screen schemesCreate and update issue type screen schemes.
delete:issue-type-screen-scheme:jiraDelete issue type screen schemesDelete issue type screen schemes.
read:issue-type.property:jiraView issue type propertiesView issue type properties.
write:issue-type.property:jiraCreate and update issue type propertiesCreate and update issue type properties.
delete:issue-type.property:jiraDelete issue type propertiesDelete issue type properties.
read:issue.watcher:jiraView issue watchersView issue watchers.
write:issue.watcher:jiraCreate and update issue watchersCreate and update issue watchers.
read:issue-worklog:jiraView issue worklogsView issue worklogs.
write:issue-worklog:jiraCreate and update issue worklogsCreate and update issue worklogs.
delete:issue-worklog:jiraDelete issue worklogsDelete issue worklogs.
read:issue-worklog.property:jiraView issue worklog propertiesView issue worklog properties.
write:issue-worklog.property:jiraCreate and update issue worklog propertiesCreate and update issue worklog properties.
delete:issue-worklog.property:jiraDelete issue worklog propertiesDelete issue worklog properties.
read:issue-field-values:jiraView issue field valuesesView issue field valueses.
read:issue-security-level:jiraView issue security levelsView issue security levels.
read:issue-status:jiraView issue statusesView issue statuses.
read:issue-type-hierarchy:jiraRead issue type hierarchiesRead issue type hierarchies.
read:issue-type-transition:jiraView issue type transitionsView issue type transitions.
read:issue.changelog:jiraView issue changelogsView issue changelogs.
read:issue.transition:jiraView issue transitionsView issue transitions.
write:issue.vote:jiraCreate and update issue votesCreate and update issue votes.
read:issue-event:jiraRead issue eventsRead issue events.
read:jira-expressions:jiraView jira expressionsView jira expressions.
read:user:jiraView usersView users.
read:user.columns:jiraView user columnsView user columns.
read:label:jiraView labelsView labels.
read:permission:jiraView permissionsView permissions.
write:permission:jiraCreate and update permissionsCreate and update permissions.
delete:permission:jiraDelete permissionsDelete permissions.
read:permission-scheme:jiraView permission schemesView permission schemes.
write:permission-scheme:jiraCreate and update permission schemesCreate and update permission schemes.
delete:permission-scheme:jiraDelete permission schemesDelete permission schemes.
read:project:jiraView projectsView projects.
write:project:jiraCreate and update projectsCreate and update projects.
delete:project:jiraDelete projectsDelete projects and their details, such as issue types, project lead, and avatars.
read:project-category:jiraView project categoriesView project categories.
write:project-category:jiraCreate and update project categoriesCreate and update project categories.
delete:project-category:jiraDelete project categoriesDelete project categories.
read:project.component:jiraView project componentsView project components.
write:project.component:jiraCreate and update project componentsCreate and update project components.
delete:project.component:jiraDelete project componentsDelete project components.
read:project.property:jiraView project propertiesView project properties.
write:project.property:jiraCreate and update project propertiesCreate and update project properties.
delete:project.property:jiraDelete project propertiesDelete project properties.
read:project-role:jiraView project rolesView project roles.
write:project-role:jiraCreate and update project rolesCreate and update project roles.
delete:project-role:jiraDelete project rolesDelete project roles.
read:project-version:jiraView project versionsView project versions.
write:project-version:jiraCreate and update project versionsCreate and update project versions.
delete:project-version:jiraDelete project versionsDelete project versions.
read:project.feature:jiraRead project featuresRead project features.
write:project.feature:jiraSave project featuresSave project features.
read:screen:jiraView screensView screens.
write:screen:jiraCreate and update screensCreate and update screens.
delete:screen:jiraDelete screensDelete screens.
read:screen-scheme:jiraView screen schemesView screen schemes.
write:screen-scheme:jiraCreate and update screen schemesCreate and update screen schemes.
delete:screen-scheme:jiraDelete screen schemesDelete screen schemes.
read:screen-field:jiraView screen fieldsView screen fields.
read:screen-tab:jiraView screen tabsView screen tabs.
write:screen-tab:jiraCreate and update screen tabsCreate and update screen tabs.
delete:screen-tab:jiraDelete screen tabsDelete screen tabs.
read:screenable-field:jiraView screenable fieldsView screenable fields.
write:screenable-field:jiraCreate and update screenable fieldsCreate and update screenable fields.
delete:screenable-field:jiraDelete screenable fieldsDelete screenable fields.
read:issue.time-tracking:jiraView issue time trackingsView issue time trackings.
write:issue.time-tracking:jiraCreate and update issue time trackingsCreate and update issue time trackings.
read:user.property:jiraView user propertiesView user properties.
write:user.property:jiraCreate and update user propertiesCreate and update user properties.
delete:user.property:jiraDelete user propertiesDelete user properties.
read:webhook:jiraView webhooksView webhooks.
write:webhook:jiraCreate and update webhooksCreate and update webhooks.
delete:webhook:jiraDelete webhooksDelete webhooks.
read:workflow:jiraView workflowsView workflows.
write:workflow:jiraCreate and update workflowsCreate and update workflows.
delete:workflow:jiraDelete workflowsDelete workflows.
read:workflow-scheme:jiraView workflow schemesView workflow schemes.
write:workflow-scheme:jiraCreate and update workflow schemesCreate and update workflow schemes.
delete:workflow-scheme:jiraDelete workflow schemesDelete workflow schemes.
read:status:jiraView statusesView statuses.
read:workflow.property:jiraView workflow propertiesView workflow properties.
write:workflow.property:jiraCreate and update workflow propertiesCreate and update workflow properties.
delete:workflow.property:jiraDelete workflow propertiesDelete workflow properties.
delete:async-task:jiraDelete asynchronous taskDelete asynchronous task.
read:instance-configuration:jiraView instance configurationsView instance configurations.
write:instance-configuration:jiraCreate and update instance configurationsCreate and update instance configurations.
read:jql:jiraView JQLView JQL.
validate:jql:jiraValidate JQLValidate JQL.
read:project-type:jiraView project typesView project types.
read:project.email:jiraView project emailsView project emails.
write:project.email:jiraCreate and update project emailsCreate and update project emails.
read:role:jiraView rolesView roles.
read:user-configuration:jiraView user configurationsView user configurations.
write:user-configuration:jiraCreate and update user configurationsCreate and update user configurations.
delete:user-configuration:jiraDelete user configurationsDelete user configurations.

Rate this page: