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
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
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 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.