Last updated Nov 21, 2024

Jira 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

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.
Run forge install --upgrade to apply the manifest changes to your app.

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 name	Summary	Description
`read:jira-user`	View user profiles	View user information in Jira that the user has access to, including usernames, email addresses, and avatars.
`read:jira-work`	View Jira issue data	Read Jira project and issue data, search for issues and objects associated with issues like attachments and worklogs.
`write:jira-work`	Create and manage issues	Create and edit issues in Jira, post comments as the user, create worklogs, and delete issues.
`manage:jira-project`	Manage project settings	Create and edit project settings and create new project-level objects (for example, versions and components).
`manage:jira-configuration`	Manage Jira global settings	Take Jira administration actions (for example, create projects and custom fields, view workflows, and manage issue link types).
`manage:jira-webhook`	Manage Jira webhooks	Fetch, register, refresh, and delete dynamically declared Jira webhooks.

Granular scopes

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

Scope name	Title	Description
`read:application-role:jira`	View application roles	View application roles.
`read:audit-log:jira`	View audit logs	View audit logs.
`read:avatar:jira`	View avatars	View system and custom avatars.
`write:avatar:jira`	Create and update avatars	Create and update system and custom avatars.
`delete:avatar:jira`	Delete avatars	Delete system and custom avatars.
`read:project.avatar:jira`	Read project avatars	Read project avatars.
`write:project.avatar:jira`	Create and update project avatars	Create and update project avatars.
`delete:project.avatar:jira`	Delete project avatars	Delete project avatars.
`read:dashboard:jira`	View dashboards	View dashboards.
`write:dashboard:jira`	Create and update dashboards	Create and update dashboards.
`delete:dashboard:jira`	Delete dashboards	Delete dashboards.
`read:dashboard.property:jira`	View dashboard properties	View dashboard properties.
`write:dashboard.property:jira`	Create and update dashboard properties	Create and update dashboard properties.
`delete:dashboard.property:jira`	Delete dashboard properties	Delete dashboard properties.
`read:filter:jira`	View filters	View filters.
`write:filter:jira`	Create and update filters	Create and update filters.
`delete:filter:jira`	Delete filters	Delete filters.
`read:filter.column:jira`	View filter columns	View filter columns.
`write:filter.column:jira`	Create and update filter columns	Create and update filter columns.
`delete:filter.column:jira`	Delete filter columns	Delete filter columns.
`read:filter.default-share-scope:jira`	View filter default share scopes	View filter default share scopes.
`write:filter.default-share-scope:jira`	Create and update filter default share scopes	Create and update filter default share scopes.
`read:group:jira`	View groups	View user groups.
`write:group:jira`	Create and update groups	Create and update user groups.
`delete:group:jira`	Delete groups	Delete user groups.
`read:license:jira`	View licenses	View licenses.
`read:issue:jira`	View issues	View issues.
`write:issue:jira`	Create and update issues	Create and update issues.
`delete:issue:jira`	Delete issues	Delete issues.
`read:issue-meta:jira`	View issue meta	View issue meta.
`send:notification:jira`	Send notifications	Send notifications.
`read:attachment:jira`	View attachments	View issue attachments.
`write:attachment:jira`	Create and update attachments	Create and update issue attachments.
`delete:attachment:jira`	Delete attachments	Delete issue attachments.
`read:comment:jira`	View comments	View issue comments.
`write:comment:jira`	Create and update comments	Create and update issue comments.
`delete:comment:jira`	Delete comments	Delete issue comments.
`read:comment.property:jira`	View comment properties	View issue comment properties.
`write:comment.property:jira`	Create and update comment properties	Create and update issue comment properties.
`delete:comment.property:jira`	Delete comment properties	Delete issue comment properties.
`read:field:jira`	View fields	View fields.
`write:field:jira`	Create and update fields	Create and update fields.
`delete:field:jira`	Delete fields	Delete fields.
`read:field.default-value:jira`	View field default values	View field default values.
`write:field.default-value:jira`	Create and update field default values	Create and update field default values.
`read:field.option:jira`	View field options	View field options.
`write:field.option:jira`	Create and update field options	Create and update field options.
`delete:field.option:jira`	Delete field options	Delete field options.
`read:field-configuration-scheme:jira`	View field configuration schemes	View field configuration schemes.
`write:field-configuration-scheme:jira`	Create and update field configuration schemes	Create and update field configuration schemes.
`delete:field-configuration-scheme:jira`	Delete field configurations	Delete field configuration schemes.
`read:custom-field-contextual-configuration:jira`	Read custom field contextual configurations	Read custom field contextual configurations.
`write:custom-field-contextual-configuration:jira`	Save custom field contextual configurations	Save custom field contextual configurations.
`read:field-configuration:jira`	Read field configurations	Read field configurations.
`write:field-configuration:jira`	Save field configurations	Save field configurations.
`delete:field-configuration:jira`	Delete field configurations	Delete field configurations.
`read:field.options:jira`	Read field options	Read field options.
`read:issue-link:jira`	View issue links	View issue links.
`write:issue-link:jira`	Create and update issue links	Create and update issue links.
`delete:issue-link:jira`	Delete issue links	Delete issue links.
`read:issue-link-type:jira`	View issue link types	View issue link types.
`write:issue-link-type:jira`	Create and update issue link types	Create and update issue link types.
`delete:issue-link-type:jira`	Delete issue link types	Delete issue link types.
`read:notification-scheme:jira`	View notification schemes	View notification schemes.
`read:priority:jira`	View priorities	View priorities.
`read:issue.property:jira`	View issue properties	View issue properties.
`write:issue.property:jira`	Create and update issue properties	Create and update issue properties.
`delete:issue.property:jira`	Delete issue properties	Delete issue properties.
`read:issue.remote-link:jira`	View issue remote links	View issue remote links.
`write:issue.remote-link:jira`	Create and update issue remote links	Create and update issue remote links.
`delete:issue.remote-link:jira`	Delete issue remote links	Delete issue remote links.
`read:resolution:jira`	View resolutions	View resolutions.
`read:issue-details:jira`	View issue details	View issue details.
`read:issue-security-scheme:jira`	View issue security schemes	View issue security schemes.
`read:issue-type:jira`	View issue types	View issue types.
`write:issue-type:jira`	Create and update issue types	Create and update issue types.
`delete:issue-type:jira`	Delete issue types	Delete issue types.
`read:issue-type-scheme:jira`	View issue type schemes	View issue type schemes.
`write:issue-type-scheme:jira`	Create and update issue type schemes	Create and update issue type schemes.
`delete:issue-type-scheme:jira`	Delete issue type schemes	Delete issue type schemes.
`read:issue-type-screen-scheme:jira`	View issue type screen schemes	View issue type screen schemes.
`write:issue-type-screen-scheme:jira`	Create and update issue type screen schemes	Create and update issue type screen schemes.
`delete:issue-type-screen-scheme:jira`	Delete issue type screen schemes	Delete issue type screen schemes.
`read:issue-type.property:jira`	View issue type properties	View issue type properties.
`write:issue-type.property:jira`	Create and update issue type properties	Create and update issue type properties.
`delete:issue-type.property:jira`	Delete issue type properties	Delete issue type properties.
`read:issue.watcher:jira`	View issue watchers	View issue watchers.
`write:issue.watcher:jira`	Create and update issue watchers	Create and update issue watchers.
`read:issue-worklog:jira`	View issue worklogs	View issue worklogs.
`write:issue-worklog:jira`	Create and update issue worklogs	Create and update issue worklogs.
`delete:issue-worklog:jira`	Delete issue worklogs	Delete issue worklogs.
`read:issue-worklog.property:jira`	View issue worklog properties	View issue worklog properties.
`write:issue-worklog.property:jira`	Create and update issue worklog properties	Create and update issue worklog properties.
`delete:issue-worklog.property:jira`	Delete issue worklog properties	Delete issue worklog properties.
`read:issue-field-values:jira`	View issue field valueses	View issue field valueses.
`read:issue-security-level:jira`	View issue security levels	View issue security levels.
`read:issue-status:jira`	View issue statuses	View issue statuses.
`read:issue-type-hierarchy:jira`	Read issue type hierarchies	Read issue type hierarchies.
`read:issue-type-transition:jira`	View issue type transitions	View issue type transitions.
`read:issue.changelog:jira`	View issue changelogs	View issue changelogs.
`read:issue.transition:jira`	View issue transitions	View issue transitions.
`write:issue.vote:jira`	Create and update issue votes	Create and update issue votes.
`read:issue-event:jira`	Read issue events	Read issue events.
`read:jira-expressions:jira`	View jira expressions	View jira expressions.
`read:user:jira`	View users	View users.
`read:user.columns:jira`	View user columns	View user columns.
`read:label:jira`	View labels	View labels.
`read:permission:jira`	View permissions	View permissions.
`write:permission:jira`	Create and update permissions	Create and update permissions.
`delete:permission:jira`	Delete permissions	Delete permissions.
`read:permission-scheme:jira`	View permission schemes	View permission schemes.
`write:permission-scheme:jira`	Create and update permission schemes	Create and update permission schemes.
`delete:permission-scheme:jira`	Delete permission schemes	Delete permission schemes.
`read:project:jira`	View projects	View projects.
`write:project:jira`	Create and update projects	Create and update projects.
`delete:project:jira`	Delete projects	Delete projects and their details, such as issue types, project lead, and avatars.
`read:project-category:jira`	View project categories	View project categories.
`write:project-category:jira`	Create and update project categories	Create and update project categories.
`delete:project-category:jira`	Delete project categories	Delete project categories.
`read:project.component:jira`	View project components	View project components.
`write:project.component:jira`	Create and update project components	Create and update project components.
`delete:project.component:jira`	Delete project components	Delete project components.
`read:project.property:jira`	View project properties	View project properties.
`write:project.property:jira`	Create and update project properties	Create and update project properties.
`delete:project.property:jira`	Delete project properties	Delete project properties.
`read:project-role:jira`	View project roles	View project roles.
`write:project-role:jira`	Create and update project roles	Create and update project roles.
`delete:project-role:jira`	Delete project roles	Delete project roles.
`read:project-version:jira`	View project versions	View project versions.
`write:project-version:jira`	Create and update project versions	Create and update project versions.
`delete:project-version:jira`	Delete project versions	Delete project versions.
`read:project.feature:jira`	Read project features	Read project features.
`write:project.feature:jira`	Save project features	Save project features.
`read:screen:jira`	View screens	View screens.
`write:screen:jira`	Create and update screens	Create and update screens.
`delete:screen:jira`	Delete screens	Delete screens.
`read:screen-scheme:jira`	View screen schemes	View screen schemes.
`write:screen-scheme:jira`	Create and update screen schemes	Create and update screen schemes.
`delete:screen-scheme:jira`	Delete screen schemes	Delete screen schemes.
`read:screen-field:jira`	View screen fields	View screen fields.
`read:screen-tab:jira`	View screen tabs	View screen tabs.
`write:screen-tab:jira`	Create and update screen tabs	Create and update screen tabs.
`delete:screen-tab:jira`	Delete screen tabs	Delete screen tabs.
`read:screenable-field:jira`	View screenable fields	View screenable fields.
`write:screenable-field:jira`	Create and update screenable fields	Create and update screenable fields.
`delete:screenable-field:jira`	Delete screenable fields	Delete screenable fields.
`read:issue.time-tracking:jira`	View issue time trackings	View issue time trackings.
`write:issue.time-tracking:jira`	Create and update issue time trackings	Create and update issue time trackings.
`read:user.property:jira`	View user properties	View user properties.
`write:user.property:jira`	Create and update user properties	Create and update user properties.
`delete:user.property:jira`	Delete user properties	Delete user properties.
`read:webhook:jira`	View webhooks	View webhooks.
`write:webhook:jira`	Create and update webhooks	Create and update webhooks.
`delete:webhook:jira`	Delete webhooks	Delete webhooks.
`read:workflow:jira`	View workflows	View workflows.
`write:workflow:jira`	Create and update workflows	Create and update workflows.
`delete:workflow:jira`	Delete workflows	Delete workflows.
`read:workflow-scheme:jira`	View workflow schemes	View workflow schemes.
`write:workflow-scheme:jira`	Create and update workflow schemes	Create and update workflow schemes.
`delete:workflow-scheme:jira`	Delete workflow schemes	Delete workflow schemes.
`read:status:jira`	View statuses	View statuses.
`read:workflow.property:jira`	View workflow properties	View workflow properties.
`write:workflow.property:jira`	Create and update workflow properties	Create and update workflow properties.
`delete:workflow.property:jira`	Delete workflow properties	Delete workflow properties.
`delete:async-task:jira`	Delete asynchronous task	Delete asynchronous task.
`read:instance-configuration:jira`	View instance configurations	View instance configurations.
`write:instance-configuration:jira`	Create and update instance configurations	Create and update instance configurations.
`read:jql:jira`	View JQL	View JQL.
`validate:jql:jira`	Validate JQL	Validate JQL.
`read:project-type:jira`	View project types	View project types.
`read:project.email:jira`	View project emails	View project emails.
`write:project.email:jira`	Create and update project emails	Create and update project emails.
`read:role:jira`	View roles	View roles.
`read:user-configuration:jira`	View user configurations	View user configurations.
`write:user-configuration:jira`	Create and update user configurations	Create and update user configurations.
`delete:user-configuration:jira`	Delete user configurations	Delete user configurations.
`read:email-address:jira`	Read email addresses	View email addresses of all users regardless of user’s profile visibility settings.