OAuth clients provide credentials according to the OAuth 2.0 standard. Credentials are managed by Dynatrace administrators and are used to set up integrations between Dynatrace and external systems or automate account management, or build user-facing applications.
Dynatrace supports two OAuth 2.0 grant types:
This needs to be an active user, and either a service user or any user with account-user-management permission.
You can only access your client secret once upon creation. You can't reveal it afterward.
Use the client credentials flow for machine-to-machine integrations where no user is involved. A backend service authenticates directly using its client ID and secret.
After you create the OAuth2 client, request the bearer token from the Dynatrace SSO system via an API call.
POST |
|
Content type |
|
Provide the following parameters in the request body. Be sure to URL-encode all values!
| Parameter | Value |
|---|---|
grant_type |
|
client_id |
|
client_secret |
|
scope | A list of required scopes separated by a whitespace, for example 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. |
resource |
|
In this example, the response of the request contains the bearer token, which you need to pass to the API call.
{"token_type": "Bearer","resource": "urn:dtaccount:{dynatrace-account-urn}","access_token": "{your-bearer-token}","expires_in": 300,"scope": "app-engine:apps:run storage:buckets:read storage:logs:read"}
| Parameter | Value |
|---|---|
token_type | Required The type of token issued. Typically, the string Bearer. |
resource | Required Specifies the target resource or account context for which the token is valid. |
access_token | Required The actual token used to authenticate API requests, issued by the authorization server. |
expires_in | Recommended Specifies the token's lifetime in seconds. |
scope | Optional Defines the permissions granted to the access token. |
To authenticate a call, attach the token to the Authorization HTTP header preceding the Bearer realm.
--header 'Authorization: Bearer abcdefjhij1234567890'
The following example shows the authentication.
curl --request GET \--url https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/users \--header 'Authorization: Bearer abcdefjhij1234567890' \
Use the authorization code flow for applications that act on behalf of a logged-in Dynatrace user. This flow requires PKCE (Proof Key for Code Exchange) using the S256 method.
Before redirecting the user, generate a code_verifier and derive its code_challenge. These values bind the authorization request to the token exchange step, preventing interception attacks.
# Generate a cryptographically random code_verifier (43–128 characters)CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=\n' | tr '+/' '-_')# Derive the code_challenge: BASE64URL(SHA256(code_verifier))CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -binary -sha256 | openssl base64 | tr -d '=\n' | tr '+/' '-_')
Store the CODE_VERIFIER securely in your application's session. You need it in Step 3.
Construct the following URL and redirect the user's browser to it. After the user authenticates with Dynatrace SSO, they are redirected back to your redirect_uri with an authorization code and the state value you provided.
GET |
|
Example URL (line-broken for readability):
https://sso.dynatrace.com/oauth2/authorize?response_type=code&client_id={your-client-id}&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope={space-separated-scopes}&state={random-csrf-token}&code_challenge={code-challenge}&code_challenge_method=S256
Provide the following parameters. Be sure to URL-encode all values.
| Parameter | Value |
|---|---|
response_type | Required Must be |
client_id | Required Your OAuth client ID, for example, |
redirect_uri | Required The URL at which your application handles the authorization response. Must exactly match the Redirect URI registered when creating the OAuth client, for example, |
scope | Required A list of required scopes separated by a whitespace. Must be a subset of the permissions configured for this client. |
state | Required A random, unpredictable value your application generates to protect against CSRF attacks. Verify that the value returned in the callback matches what you sent. |
code_challenge | Required The PKCE code challenge derived in Step 1. |
code_challenge_method | Required Must be |
The redirect_uri must exactly match the value registered when creating the OAuth client. Any mismatch causes the authorization request to fail.
When the user completes authentication, Dynatrace redirects to your redirect_uri with a code query parameter. Exchange this code for tokens by sending a POST request to the token endpoint.
POST |
|
Content type |
|
curl --request POST \--url 'https://sso.dynatrace.com/sso/oauth2/token' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'grant_type=authorization_code' \--data-urlencode 'code={authorization-code}' \--data-urlencode 'redirect_uri=https://example.com/oauth/callback' \--data-urlencode 'client_id={your-client-id}' \--data-urlencode 'client_secret={your-client-secret}' \--data-urlencode 'code_verifier={your-code-verifier}'
| Parameter | Value |
|---|---|
grant_type | Required Must be |
code | Required The authorization code received in the callback redirect. |
redirect_uri | Required Must exactly match the |
client_id | Required Your OAuth client ID. |
client_secret | Required Your OAuth client secret. |
code_verifier | Required The original |
{"access_token": "{your-bearer-token}","token_type": "Bearer","expires_in": 600,"refresh_token": "{your-refresh-token}"}
| Parameter | Value |
|---|---|
access_token | Required The bearer token used to authenticate API requests. |
token_type | Required The type of token issued. Always |
expires_in | Recommended The token's lifetime in seconds. Typically 600 seconds (10 minutes). |
refresh_token | Recommended A long-lived token used to obtain new access tokens without re-prompting the user. See Step 5. |
Authorization codes are single-use and expire shortly after issuance. If the token exchange fails, restart the flow from Step 2.
To authenticate a call, attach the access token to the Authorization HTTP header preceding the Bearer realm.
--header 'Authorization: Bearer {your-bearer-token}'
The following example calls the MCP gateway for the environment https://abc.apps.dynatrace.com:
curl --request POST \--url 'https://abc.apps.dynatrace.com/platform-reserved/mcp-gateway/v0.1/servers/dynatrace-mcp/mcp' \--header 'Authorization: Bearer {your-bearer-token}' \--header 'Content-Type: application/json' \--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0"}}}'
Access tokens expire after 600 seconds (10 minutes). Use the refresh token to obtain a new access token without re-prompting the user.
POST |
|
Content type |
|
curl --request POST \--url 'https://sso.dynatrace.com/sso/oauth2/token' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'grant_type=refresh_token' \--data-urlencode 'refresh_token={your-refresh-token}' \--data-urlencode 'client_id={your-client-id}' \--data-urlencode 'client_secret={your-client-secret}'
| Parameter | Value |
|---|---|
grant_type | Required Must be |
refresh_token | Required The refresh token received in Step 3. |
client_id | Required Your OAuth client ID. |
client_secret | Required Your OAuth client secret. |
The response contains a new access_token with a fresh expires_in value.