Rate this page:

Permissions

The permissions section of the manifest.yml file controls your app's access to remote resources.

OAuth 2 scopes

The scopes list declares which OAuth 2 scopes are required by your app when using the authenticated Product Fetch APIs, and Product events.

Example

Define each scope on a new line. Your app should use the minimum set of scopes required.

1
2
3
4
permissions:
  scopes:
    - 'read:confluence-content.summary'
    - 'write:jira-work'

If your app requires no OAuth 2 permissions, you must provide an empty scopes list as in the example below.

1
2
permissions:
  scopes: []

Note, Forge apps deployed in the development environment always receive all available OAuth 2 scopes.

Forge scopes

Certain platform features, such as the App storage API, are also authenticated using OAuth 2.

ScopeDescription
storage:appEnables the App storage API.
report:personal-dataEnables the User privacy API.

Product scopes

In addition to the reference tables below, you can find the required scopes in each product's REST API documentation and event documentation on a per-operation basis in the OAuth scopes required field. Note, not all operations support OAuth 2 authentication.

Confluence Cloud

The Confluence Cloud REST API and Confluence event scopes.

ScopeDescription
read:confluence-content.allRead 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 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.
write:confluence-contentCreate pages, blogs, comments, and questions.
read:confluence-space.summaryRead a summary of space information without expansions.
write:confluence-spaceCreate, update, and delete space information.
write:confluence-fileUpload attachments.
read:confluence-propsRead content properties.
write:confluence-propsWrite content properties.
search:confluenceSearch 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.
manage:confluence-configurationManage global settings.

Jira Cloud platform

The Jira Cloud REST API and Jira event scopes.

ScopeDescription
read:jira-userView user information in Jira that you have access to, including usernames, email addresses, and avatars.
read:jira-workRead project and issue data, and search for issues and objects associated with issues, such as attachments and worklogs.
write:jira-workCreate and edit issues in Jira, post comments, create worklogs, and delete issues.
manage:jira-projectCreate and edit project settings, and create new project-level objects, such as versions and components.
manage:jira-configurationConfigure Jira settings that require Jira administrator permissions, such as create projects and custom fields, view workflows, and manage issue link types.

Content permissions

The content section declares which Content Security Policy (CSP) options are required by your app when using custom UI.

Scripts

The scripts list declares which sources are allowed for an app's script-src policy.

Example

In the example below, script-src 'unsafe-hashes' is included in the CSP header for all modules using custom UI:

1
2
3
4
permissions:
  content:
    scripts:
      - 'unsafe-hashes'
SourceDescription
unsafe-inlineAllows the use of inline resources, such as inline <script> elements, javascript: URLs, and inline event handlers.
unsafe-hashesAllows the use of specific inline event handlers.
unsafe-evalAllows the use of eval() and similar methods for creating code from strings.
<sha-algorithm>-<base64-value>Allows a specific script to be executed, provided it matches the hash declared here. The only valid hash algorithms are: sha256, sha384, and sha512.

Styles

The styles list declares which sources are allowed for an app's style-src policy.

Example

In the example below, style-src 'unsafe-inline' is included in the CSP header for all modules using custom UI:

1
2
3
4
permissions:
  content:
    styles:
      - 'unsafe-inline'
SourceDescription
unsafe-inlineAllows the use of inline resources, such as inline <script> elements, javascript: URLs, and inline event handlers.

External permissions

The external section declares which external resources your custom UI app is allowed to access. In each section, you can add a list of external domains or URLs, which end up as a source in an equivalent CSP directive.

Example

In the example below, connect-src *.example-dev.com; media-src https://www.example-dev.com/video.mp4 is included in the CSP header for all modules using custom UI:

1
2
3
4
5
6
7
permissions:
  external:
    fetch:
      client:
        - '*.example-dev.com'
    media:
      - 'https://www.example-dev.com/video.mp4'

Valid URL and domain formats

URLs and domains must be in one of the following formats:

  • An https or wss URL, such as https://www.example-dev.com
  • A valid domain name, such as www.example-dev.com
  • A valid wildcard domain starting with *, such as *.example-dev.com

They must also not contain any invalid special characters. You can check the domain or URL against the following regex pattern:

1
^(\*\.)?[.a-zA-Z0-9_\-\/:~#%?=&]+$

Fetch

The fetch section declares which external sources are allowed for an app's connect-src policy.

Example

In the example below, connect-src *.example-dev.com is included in the CSP header for all modules using custom UI:

1
2
3
4
5
permissions:
  external:
    fetch:
      client:
        - '*.example-dev.com'

Images

The images list declares which external sources are allowed for an app's img-src policy.

Example

In the example below, img-src https://www.example-dev.com/image.png is included in the CSP header for all modules using custom UI:

1
2
3
4
permissions:
  external:
    images:
      - 'https://www.example-dev.com/image.png'

Media

The media list declares which external sources are allowed for an app's media-src policy.

Example

In the example below, media-src https://www.example-dev.com/video.mp4 is included in the CSP header for all modules using custom UI:

1
2
3
4
permissions:
  external:
    media:
      - 'https://www.example-dev.com/video.mp4'

Scripts

The scripts list declares which external sources are allowed for an app's script-src policy.

Example

In the example below, script-src https://www.example-dev.com/script.js is included in the CSP header for all modules using custom UI:

1
2
3
4
permissions:
  external:
    scripts:
      - 'https://www.example-dev.com/script.js'

Styles

The styles list declares which external styles are allowed for an app's style-src policy.

Example

In the example below, style-src https://www.example-dev.com/stylesheet.css is included in the CSP header for all modules using custom UI:

1
2
3
4
permissions:
  external:
    styles:
      - 'https://www.example-dev.com/stylesheet.css'

Rate this page: