Add scopes to use Dynatrace APIs

Requests to the Dynatrace API need authorization via OAuth. When you consume these APIs in your app, directly or via the provided SDK packages, the platform takes care of the authorization for you. During the usage of an app, the user's permissions are used for authorization. During development, they're the developer's permissions, respectively.

The fact that the user's permissions are used for authorization could lead to potential security problems, as an app could misuse the user's permissions and perform malicious activity. Therefore, the Dynatrace platform requires an app to provide all the needed permissions within the app configuration file. When executing an app, app permissions are intersected with user permissions to adhere to the principle of least privilege.

Making this list of required permissions transparent to Dynatrace users and administrators allows them to decide if a particular app is safe to run in their environment. Having specific permissions defined in the app configuration file doesn't necessarily mean that the app uses it.

Find the required scopes

You can find all scopes for every exposed function of Dynatrace SDK packages on the corresponding reference page. Additionally, you can find a complete list of available scopes on the IAM service reference page.

Add the required scopes

Once you have figured out the needed scopes, add them to your app configuration file:

app.config.json

{
  "environmentUrl": "<Your-Environment-URL>",
  "app": {
    "id": "<Your-App-ID>",
    "name": "<Your-App-Name>",
    "version": "0.0.0",
    "description": "<Your-App-Description>",
    "scopes": [
      {
        "name": "storage:events:read",
        "comment": "allows to query events from Grail"
      },
      {
        "name": "state:app-states:read",
        "comment": "allows to read app state"
      }
    ]
  }
}

app.config.ts

import type { CliOptions } from 'dt-app';

const config: CliOptions = {
  environmentUrl: '<Your-Environment-URL>',
  app: {
    id: '<Your-App-ID>',
    name: '<Your-App-Name>',
    version: '0.0.0',
    description: '<Your-App-Description>',
    scopes: [
      {
        name: 'storage:events:read',
        comment: 'allows to query events from Grail'
      },
      {
        name: 'state:app-states:read',
        comment: 'allows to read app state'
      }
    ]
  }
}

module.exports = config;

Caution

After changing the scopes in the app configuration file, you must restart the local development server to apply the changes.