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 Service Management permissions also control access to data and aren't overridden by scopes. For example, if a user does not have Jira Administrator Global permission then the Create customers operation won’t be able to access customer data even if the app has the manage:servicedesk-customer 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 Jira Service Management 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 Service Management 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 Jira Service Management 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

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.
read:servicedesk-requestView Jira Service Desk request dataRead customer request data, including approvals, attachments, comments, request participants, and status/transitions.
Read service desk and request types, including searching for request types and reading request type fields, properties and groups.
write:servicedesk-requestCreate and manage Jira Service Desk requestsCreate and edit customer requests, including add comments and attachments, approve, share (add request participants), subscribe, and transition.
manage:servicedesk-customerManage Jira Service Desk customers and organizationsCreate, manage and delete customers and organizations.
Add and remove customers and organizations from service desks.

Granular scopes

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

Scope nameTitleDescription
read:customer:jira-service-managementView CustomersView customer (user) account information.
write:customer:jira-service-managementCreate and update customersCreate and update customer (user) accounts.
read:organization:jira-service-managementView organizationsView organization information.
write:organization:jira-service-managementCreate and update organizationsCreate and update organizations.
delete:organization:jira-service-managementDelete organizationsDelete organizations.
read:organization.user:jira-service-managementView organization's usersView an organization’s users.
write:organization.user:jira-service-managementAdd organization's usersAdd users to an organization
delete:organization.user:jira-service-managementDelete organization usersRemove users from an organization.
read:organization.property:jira-service-managementView organization propertiesView organization entity properties.
write:organization.property:jira-service-managementCreate and update organization propertiesCreate and update organization entity properties.
delete:organization.property:jira-service-managementDelete organization propertiesDelete organization entity properties.
read:servicedesk:jira-service-managementView servicedesksSearch and view service desks.
read:servicedesk.organization:jira-service-managementView servicedesk organizationsView organizations associated with service desk.
write:servicedesk.organization:jira-service-managementAdd organizations to service desksAdd organizations to service desks.
delete:servicedesk.organization:jira-service-managementRemove organizations from service desksRemove organizations from service desks.
read:servicedesk.customer:jira-service-managementView servicedesk customersView customers associated with service desks.
write:servicedesk.customer:jira-service-managementAdd servicedesk customersAdd customers to service desks.
delete:servicedesk.customer:jira-service-managementRemove servicedesk customersRemove customers from service desks.
read:requesttype:jira-service-managementView requesttypesSearch and view request types.
write:requesttype:jira-service-managementCreate and update requesttypesCreate and update request types.
read:servicedesk.property:jira-service-managementView servicedesk propertiesView service desk entity properties.
write:servicedesk.property:jira-service-managementCreate and update servicedesk propertiesCreate and update service desk entity properties.
delete:servicedesk.property:jira-service-managementDelete servicedesk propertiesDelete service desk entity properties.
read:requesttype.property:jira-service-managementView requesttype propertiesView request type entity properties.
write:requesttype.property:jira-service-managementCreate and update requesttype propertiesCreate and update request type entity properties.
delete:requesttype.property:jira-service-managementDelete requesttype propertiesDelete request type entity properties.
read:queue:jira-service-managementView queuesView queues.
read:request:jira-service-managementView requestsSearch and view requests.
write:request:jira-service-managementCreate and update requestsCreate and update requests.
read:request.approval:jira-service-managementView request approvalsView request approvals.
write:request.approval:jira-service-managementAction request approvalsAction request approvals, for example, approve, deny, and alike.
read:request.participant:jira-service-managementView request participantsView request participants (users).
write:request.participant:jira-service-managementAdd request participantsAdd participants (users) to requests.
delete:request.participant:jira-service-managementRemove request participantsRemove participants (users) from requests.
read:request.action:jira-service-managementView request actionsView actions that can be performed on requests.
read:request.comment:jira-service-managementView request commentsView request comments.
write:request.comment:jira-service-managementCreate and update request commentsCreate and update request comments.
read:request.sla:jira-service-managementView request SLAsView request SLAs.
read:request.attachment:jira-service-managementView request attachmentsView request attachments.
write:request.attachment:jira-service-managementAdd request attachmentsAdd attachments to requests.
read:request.status:jira-service-managementView request statusesView request status and transition information.
write:request.status:jira-service-managementExecute request transitionsExecute transitions on requests.
read:request.feedback:jira-service-managementView request feedbackView request feedback.
write:request.feedback:jira-service-managementCreate and update request feedbackCreate and update request feedback.
delete:request.feedback:jira-service-managementDelete request feedbackDelete request feedback.
read:request.notification:jira-service-managementView request notificationsView subscription status of users for requests.
write:request.notification:jira-service-managementCreate and update request notificationsSubscribe users to requests and update subscription status.
delete:request.notification:jira-service-managementRemove request notificationsUnsubscribe uses from requests.
read:knowledgebase:jira-service-managementView knowledgebaseSearch and view knowledgebase articles.

Rate this page: