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.

For details on OAuth clients, see OAuth clients.

Token format

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

Token example

dt0s01.ST2EY72KQINMH574WMNVI7YN.G3DFPBEJYMODIDAEX454M7YWBUVEFOWKPRVMWFASS64NFH52PX6BNDVFFM572RZM

Token components

Component name

Component description

prefix

The prefix identifies the token type.

In our example: dt0s01

See Token prefixes below for a table of standard prefixes.

public portion

The public portion of the token is a 24-character public identifier.

In our example: ST2EY72KQINMH574WMNVI7YN

token identifier

The token identifier is the combination of the prefix and the public portion. A token identifier can be safely displayed in the UI and can be used for logging purposes.

In our example: dt0s01.ST2EY72KQINMH574WMNVI7YN

secret portion

The secret portion of the token is a 64-character string that should be treated like a password:

  • Don't display it
  • Don't store it in log files
  • Rotate it instantly if it's leaked

In our example: G3DFPBEJYMODIDAEX454M7YWBUVEFOWKPRVMWFASS64NFH52PX6BNDVFFM572RZM

Token prefixes

Prefix

Description

dt0s01

This is an API token. It's used as an authorization method: a valid token allows the user to make changes within the Dynatrace account through SCIM.

  • It is generated once.
  • Do not reveal the secret portion of a dt0s01 token.
  • The public portion is used for identification in the web UI, but you generally should not reveal it (or any portion of this token).
  • This token remains in effect until invalidated by the customer, so you must rotate it instantly if it is ever leaked.

dt0s02

OAuth2 Clients created by users through Account Management to be used with Dynatrace Apps and Account Management API.

dt0s03

OAuth2 Clients for internal and external services and integrations.

dt0s04

Chat and identity linking.

dt0s06

This is an OAuth2 Refresh Token, which is used to retrieve a new Access Token and generally changes frequently (typically every 5 to 15 minutes).

dt0s08

OAuth2 Clients for internal and external services and integrations.

dt0s09

Chat and identity linking.

Generate a token

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.

To change the scope of an existing token, use the PUT a token call of the Access tokens API. Note that you need to submit the existing scopes if you want to keep them. Any existing scope missing in the payload is removed.

Alternatively, you can use the POST a token call to generate a token.

Token scopes

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.

Authentication in the API Explorer

Select the lock Lock icon next to any end point to display information about the OAuth 2.0 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 OAuth 2.0 token into the global Available authorizations dialog, you can unlock all related API endpoints.

Related topics