• Home
  • Dynatrace API
  • Basics
  • Tokens and authentication

Dynatrace API - Tokens and authentication

To be authenticated to use the Dynatrace API, you need a valid access token or a valid personal access token. Access to the API is fine-grained, meaning that you also need the proper scopes assigned to the token. See the description of each request to find out which scopes are required to use it.

Token format

Dynatrace uses a unique token format consisting of three components separated by dots (.).

dt0c01.ST2EY72KQINMH574WMNVI7YN.G3DFPBEJYMODIDAEX454M7YWBUVEFOWKPRVMWFASS64NFH52PX6BNDVFFM572RZM

dt0c01Prefix to identify the token.
ST2...7YN

Public portion of token

A 24-character public identifier of the token. This value can be safely displayed in the UI and can be used for logging purposes.

G3D...RZM

Secret portion of token

A 64-character secret portion of the token, which can be treated like a password and therefore doesn’t need to be displayed in the Dynatrace web UI (following initial creation) or stored in log files.

Generate a token

To generate an access token

  1. In the Dynatrace menu, select Access tokens.
  2. Select Generate new token.
  3. Enter a name for your token.
    Dynatrace doesn't enforce unique token names. You can create multiple tokens with the same name. Be sure to provide a meaningful name for each token you generate. Proper naming helps you to efficiently manage your tokens and perhaps delete them when they're no longer needed.
  4. Select the required scopes for the token.
  5. Select Generate.
  6. Copy the generated token to the clipboard. Store the token in a password manager for future use.

    You can only access your token once upon creation. You can't reveal it afterwards.

To generate a personal access token

  1. Select the user menu in the upper-right corner of the page.
  2. Select Personal access tokens.
  3. Select Generate new token.
  4. Enter a name for your token.
    Dynatrace doesn't enforce unique token names. You can create multiple tokens with the same name. Be sure to provide a meaningful name for each token you generate. Proper naming helps you to efficiently manage your tokens and perhaps delete them when they're no longer needed.
  5. Select the required scopes for the token.
  6. Select Generate.
  7. Copy the generated token to the clipboard. Store the token in a password manager for future use.

    You can only access your token once upon creation. You can't reveal it afterwards.

You can assign multiple scopes to a single token, or you can generate several tokens, each with different access levels and use them accordingly—check your organization's security policies for the best practice. Note that you can't change the scope set of an existing token.

Alternatively, you can use the POST a token call of the Access tokens API to generate a token.

Token scopes

Dynatrace provides the following permissions for API tokens. You can set them in the web UI as described above or via the Access tokens API. Some scopes are only available via API.

NameAPI valueDescription

API v2

Read metricsmetrics.readGrants access to GET requests of the Metrics API v2.
Write metricsmetrics.writeGrants access to the DELETE a custom metric request of the Metrics API v2.
Ingest metricsmetrics.ingestGrants access to the POST ingest data points request of the Metrics v2 API.
Read logslogs.readGrants access to the GET requests of the Log Monitoring API v2
Ingest logslogs.ingestGrants access to the POST ingest logs request of the Log Monitoring API v2.
Ingest OpenTelemetry tracesopenTelemetryTrace.ingestAllows to ingest OpenTelemetry traces.
Read entitiesentities.readGrants access to GET requests of the Monitored entities and Custom tags APIs.
Write entitiesentities.writeGrants access to POST, PUT, and DELETE requests of the Monitored entities and Custom tags APIs.
Read problemsproblems.readGrants access to GET requests of the Problems API v2.
Write problemsproblems.writeGrants access to POST, PUT, and DELETE requests of the Problems API v2.
Read eventsevents.readGrants access to GET requests of the Events API v2.
Ingest eventsevents.ingestGrants access to POST request of the Events API v2.
Read network zonesnetworkZones.readGrants access to GET requests of the Network zones API.
Write network zonesnetworkZones.writeGrants access to POST, PUT, and DELETE requests of the Network zones API.
Read ActiveGatesactiveGates.readGrants access to GET requests of the ActiveGates API.
Write ActiveGatesactiveGates.writeGrants access to POST and DELETE requests of the ActiveGates API.
Read ActiveGate tokensactiveGateTokenManagement.readGrants access to GET requests of the ActiveGate tokens API.
Create ActiveGate tokensactiveGateTokenManagement.createGrants access to the POST request of the ActiveGate tokens API.
Write ActiveGate tokensactiveGateTokenManagement.writeGrants access to POST and DELETE requests of the ActiveGate tokens API.
Read extensionsextensions.readGrants access to GET requests from the Extensions section of the Extensions 2.0 API.
Write extensionsextensions.writeGrants access to POST and DELETE requests from the Extensions section of the Extensions 2.0 API.
Read extensions environment configurationextensionEnvironment.readGrants access to GET requests from the Extensions environment configuration section of the Extensions 2.0 API.
Write extensions environment configurationextensionEnvironment.writeGrants access to POST, PUT, and DELETE requests from the Extensions environment configuration section of the Extensions 2.0 API.
Read extensions monitoring configurationextensionConfigurations.readGrants access to GET requests from the Extensions monitoring configuration section of the Extensions 2.0 API.
Write extensions monitoring configurationextensionConfigurations.writeGrants access to POST, PUT, and DELETE requests from the Extensions monitoring configuration section of the Extensions 2.0 API.
Read security problemssecurityProblems.readGrants access to GET requests of the Security problems API.
Write security problemssecurityProblems.writeGrants access to POST requests of the Security problems API.
Read synthetic locationssyntheticLocations.readGrants access to GET requests of the Synthetic locations API v2 and Synthetic nodes API v2.
Write synthetic locationssyntheticLocations.writeGrants access to POST, PUT, and DELETE requests of the Synthetic locations API v2 and Synthetic nodes API v2.
Read settingssettings.readGrants access to GET requests of the Settings API.
Write settingssettings.writeGrants access to POST and DELETE requests of the Settings API.
Tenant token rotationtenantTokenRotation.writeGrants access to the Tenant tokens API.
Read SLOslo.readGrants access to GET requests of the Service level objectives API.
Write SLOslo.writeGrants access to POST, PUT, and DELETE requests of the Service level objectives API.
Read API tokensapiTokens.readGrants access to GET requests of the Access tokens API.
Write API tokensapiTokens.writeGrants access to POST, PUT, and DELETE requests of the Access tokens API.
Read releasesreleases.readGrants access to the Releases API.
Read audit logsauditLogs.readGrants access to the audit log.

API v1

Read credential vault entriescredentialVault.readGrants access to GET requests of the Credential vault API.
Write credential vault entriescredentialVault.writeGrants access to POST, PUT, and DELETE requests of the Credential vault API.
Access problems and event feed, metrics, and topologyDataExportGrants access to various calls of Environment API.
Create and read synthetic monitors, locations, and nodesExternalSyntheticIntegrationGrants access to the Synthetic API.
Read synthetic monitors, locations, and nodesReadSyntheticDataGrants access to GET requests of Synthetic API.
Read configurationReadConfigGrants access to GET calls of Configuration API.
Write configurationWriteConfigGrants access to POST, PUT, and DELETE calls of Configuration API.
Change data privacy settingsDataPrivacyGrants access to Data privacy API and data privacy calls of Web application configuration API.
User sessionsDTAQLAccessGrants access to User sessions API.
Anonymize user sessions for data privacy reasonsUserSessionAnonymizationGrants access to Anonymization API.
Mobile symbolication file managementDssFileManagementGrants access to Mobile symbolication API.
Real User Monitoring JavaScript tag managementRumJavaScriptTagManagementGrants access to Real User Monitoring JavaScript API.
ActiveGate certificate managementActiveGateCertManagementAllows to configure certificate on private ActiveGates.
Data ingestDataImportAllows to import data and events from external sources.
Fetch data from a remote environmentRestRequestForwardingAllows to fetch data from remote Dynatrace environments for multi-environment dashboarding.
Capture request dataCaptureRequestDataGrants access to Request attributes API.
Read log contentLogExportGrants access to Log Monitoring API.
RUM browser extensionRumBrowserExtensionAllows the RUM browser extension to send data to Dynatrace.

PaaS

Download OneAgent and ActiveGate installersInstallerDownload

Allows download of installers via Deployment API.

Create support alertsSupportAlert

Allows creation of support alerts for crash analysis.

Other

Upload plugins using the command linePluginUploadAllows to upload OneAgent extensions via command line tool.

Dynatrace provides the following permissions for personal access tokens. You can set them in the web UI as described above or via the Access tokens API.

NameAPI valueDescription
Read API tokensapiTokens.readGrants access to GET requests of the Access tokens API.
Write API tokensapiTokens.writeGrants access to POST, PUT, and DELETE requests of the Access tokens API.
Read entitiesentities.readGrants access to GET requests of the Monitored entities and Custom tags APIs.
Write entitiesentities.writeGrants access to POST, PUT, and DELETE requests of the Monitored entities and Custom tags APIs.
Read metricsmetrics.readGrants access to GET requests of the Metrics API v2.
Write metricsmetrics.writeGrants access to the DELETE a custom metric request of the Metrics API v2.
Read network zonesnetworkZones.readGrants access to GET requests of the Network zones API.
Write network zonesnetworkZones.writeGrants access to POST, PUT, and DELETE requests of the Network zones API.
Read problemsproblems.readGrants access to GET requests of the Problems API v2.
Write problemsproblems.writeGrants access to POST, PUT, and DELETE requests of the Problems API v2.
Read releasesreleases.readGrants access to the Releases API.
Read security problemssecurityProblems.readGrants access to GET requests of the Security problems API.
Write security problemssecurityProblems.writeGrants access to POST requests of the Security problems API.
Read settingssettings.readGrants access to GET requests of the Settings API.
Write settingssettings.writeGrants access to POST and DELETE requests of the Settings API.
Read SLOslo.readGrants access to GET requests of the Service level objectives API.
Write SLOslo.writeGrants access to POST, PUT, and DELETE requests of the Service level objectives API.

Authenticate

You have two options to pass your API token: in the Authorization HTTP header or in the api-token query parameter.

We recommend that you use the Authorization header, as URLs (along with tokens passed within them) might be logged in various locations. Users might also bookmark the URLs or share them in plain text. Therefore, placing authentication tokens into the URL increases the risk that they will be captured by an attacker.

You can authenticate by attaching the token to the Authorization HTTP header preceding the Api-Token realm.

shell
--header 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890'

The following example shows authentication via HTTP header.

shell
curl --request GET \ --url https://mySampleEnv.live.dynatrace.com/api/v1/config/clusterversion \ --header 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \

You can authenticate by adding the token as the value of the api-token query parameter.

shell
curl --request GET \ --url 'https://mySampleEnv.live.dynatrace.com/api/v1/config/clusterversion?api-token=abcdefjhij1234567890' \

Authentication in the API Explorer

Select the lock Blue lock icon icon next to any end point to display information about the API tokens that secure that endpoint. Each endpoint requires a specific token type.

You can also unlock all endpoints by selecting Authorize. In the displayed dialog, you can then see which token permissions are necessary for each API endpoint. By entering your API token into the global Available authorizations dialog, you can unlock all related API endpoints.

Related topics
  • Access tokens

    Learn the concept of an access token and its scopes.