Last updatedJun 24, 2020

Rate this page:

Add scopes to call an Atlassian REST API

When using the Product Fetch APIs to make API requests on the user's behalf via asUser() your app needs to have permission from the user.

Your users are prompted to allow access the first time they use your app. The OAuth 2 scopes that you declare in the manifest file are displayed to your users on the Authorize app screen.

Each time you change a Forge app's scopes, you need to upgrade the app as shown below. Each time scopes are changed, your users will need to reauthorize the app.

Update the manifest file

App scopes must be defined in the manifest file prior to deploying the app. See Permissions for detailed information about each scope.

Use the forge lint command

You can use the forge lint command to assist you with adding missing scopes in your app.

  1. Navigate to the top-level directory of your app and run the following command:

    1
    forge lint

    If your app has missing permissions, these will be highlighted individually in the output.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    The linter checks the app code for known errors. Warnings are problems you should
    fix, but that won't stop the app code from building.
    Press Ctrl+C to cancel.
    
    /src/index.jsx
    10:57   warning  Confluence endpoint: GET /api/content requires
      "read:confluence-content.summary" scope  permission-scope-required
    
    14:56   warning  Confluence endpoint: GET /api/content requires
      "read:confluence-content.summary" scope  permission-scope-required
    
    19:51   warning  Jira endpoint: GET /rest/api/3/user requires
      "read:jira-user" scope  permission-scope-required
    
    ⚠ 3 problems (0 errors, 3 warnings)
      Run forge lint --fix to automatically fix 0 errors and 3 warnings.
  2. Rerun forge lint with the --fix argument to automatically add missing scopes to the manifest.yml file.

    1
    forge lint --fix

    The example below shows all three detected issues were fixed. You can rerun step 1 to continue investigating outstanding errors.

    1
    2
    3
    ✔ Fixed 0 errors and 3 warnings
    
    Run forge lint to review outstanding errors and warnings
  3. Run forge deploy to deploy the above changes.

  4. You'll need to complete the Upgrade the app section below to apply the changes.

Manually update the manifest file

  1. Navigate to the top-level directory of your app and open the manifest.yml file.
  2. In the permissions section, add or remove scopes as needed. For example, add the write:confluence-content scope.

    1
    2
    3
    permissions:
      scopes:
        - 'write:confluence-content'
  3. Run forge deploy to deploy the above changes.

  4. You'll need to complete the Upgrade the app section below to apply the changes.

Upgrade the app

Changes to the app's scopes won't take effect until the app is upgraded.

  1. Navigate to your app's top-level directory.
  2. Start the upgrade by running:

    1
    forge install --upgrade

    You’ll see output that’s similar to the following example.

    1
    2
    3
    4
    5
    6
    7
    ┌───────────────┬──────────────────────────────┬────────────┬─────────────┐
    │ Environment   │ Site                         │ Product    │ Scopes      │
    ├───────────────┼──────────────────────────────┼────────────┼─────────────┤
    │ ❯ development │ example-dev.atlassian.net    │ Jira       │ Latest      │
    │   development │ example-dev.atlassian.net    │ Confluence │ Latest      │
    │   production  │ example.atlassian.net        │ Confluence │ Out-of-date │
    └───────────────┴──────────────────────────────┴────────────┴─────────────┘
  3. Select the Out-of-date site to upgrade by using the arrow keys, and then press the enter key to upgrade the site.

  4. Open the authorization URL in your default browser from the CLI by pressing any key.
  5. Review the app's requested access.
  6. Select your Atlassian cloud site from the Authorize for list, then select Accept.

After completing these steps, your app runs with the updated scopes.

Rate this page: