Skip to main content

Access platform APIs from outside

The Dynatrace platform provides a set of platform APIs you can call in your Dynatrace app via their relative URL. The same is true for the app functions you deploy with your app. The platform will handle the authentication and routing to the right environment for you. However, if you want to call one of these APIs from outside the platform, for example, from any shell script, you need to follow some additional steps.

Use the correct URL​

You need to use the absolute URL of the respective API endpoint to call a platform API or app function from outside the platform. The URL for platform APIs is always following the following pattern: https://abc12345.apps.dynatrace.com/platform/<Your-Api-Endpoint>

App functions are available via this URL pattern: https://abc12345.apps.dynatrace.com/platform/app-engine/app-functions/v1/apps/<Your-App-ID>/api/<Your-Function-Name>

A complete list of available platform APIs is available in the SwaggerUI of your environment. You can find a link to swagger by using the in-product search and searching for "Dynatrace API" or access it via <ENVIRONMENT_URL>/platform/swagger-ui/index.html`

Note

You need to replace the placeholders <Your-Api-Endpoint>,<Your-App-ID>, and <Your-Function-Name> with your values.

Authentication​

Classical authentication methods like username and password don't make much sense when it comes to machine-to-machine applications such as shell scripts or services running on your backend. In these cases, on the Dynatrace platform, we use the OAuth Client Credentials Flow. The calling script provides its Client ID and Client Secret to authenticate itself and get a token to execute an API call.

The following diagram illustrates this workflow:

Create an OAuth client​

Before you can call an API from outside the platform, you need to create an OAuth client with the required scopes for yourself or your team. Currently, only account admins can create OAuth clients.

To create a new OAuth client, do the following steps:

  • Got to account settings.
  • Navigate to "Account management API" and select "Create new client".
  • You need to fill out a Service user email and, optionally a description of your OAuth client.
  • After selecting the needed OAuth scopes, click the button "Generate client" to generate the OAuth client.
  • Ensure you copy the generated client secret immediately and store it safely since it is only visible once.

Get Bearer token and call app function​

As described above, you need to pass a Bearer token to authenticate API calls. You need to retrieve the Bearer token from the token endpoint of the SSO API.

Example​

The following example shows how you can call the calculate function from your my.custom.app app via curl from outside the platform. First, you have to get a Bearer token from the SSO. You have to specify your client id, the corresponding client secret, and the scope for which you want to get a Bearer token.

curl --request POST 'https://sso.dynatrace.com/sso/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={your-client-id}' \
--data-urlencode 'client_secret={your-client-secret}' \
--data-urlencode 'scope=app-engine:apps:run storage:buckets:read storage:logs:read'
Note

In this example app-engine:apps:run and storage:logs:read are passed as scopes. app-engine:apps:run is always needed to access any function of your custom app.

This request returns the following response object, including the Bearer token you must pass to the actual API call.

{
  "scope": "app-engine:apps:run storage:buckets:read storage:logs:read",
  "token_type": "Bearer",
  "expires_in": 300,
  "access_token": "{your-bearer-token}",
  "resource": "urn:dtaccount:{dynatrace-account-urn}"
}

After getting a Bearer token, you can now call the API endpoint by passing this exact Bearer token via an authorization header:

curl --request GET 'https://abc12345.apps.dynatrace.com/platform/app-engine/app-functions/v1/apps/my.custom.app/api/calculate' \
--header 'Authorization: Bearer {your-bearer-token}'
Still have questions?
Find answers in the Dynatrace Community