Authentication for the Account Management API

The Account Management API helps you manage your account and its users. For example, you can manage access to Dynatrace environments by creating groups with various access levels and then associating these groups with users.

Recommendations

To be authenticated to use the Account Management API, you need a valid bearer token. Access to the API is fine-grained, meaning that you also need the proper permissions assigned to the token. See the description of each request to find out which permission is required to use it. The bearer token authenticates you via an OAuth2 client as a service user who is granted access to the API.

You can designate any user on your account as a service user, but we recommend that you do not use the service user for any other purpose. The service user must belong to a group that provides account user management permissions.
Create a separate Client ID for each application or integration that you build, and don't share clients between them. This approach provides you maximum control and security. Each client must have at least one scope. This enables you to authorize APIs on an application basis, as well as via the associated service user.

To obtain a token, you must create an OAuth2 client and then request the token from it.

Create an OAuth2 client

Go to Account Management. If you have more than one account, select the account you want to manage.
On the top navigation bar, go to Identity & access management > OAuth clients.
Select Create client.
Provide an email of the user who owns the client.
Provide a description for the new client.
Select the required permissions.
These are the scopes that the client will be able to grant. Tokens generated by the client might have different scope sets.
Select Create client.
Copy the generated information to the clipboard. Store it in a password manager for future use.
You can only access your client secret once upon creation. You can't reveal it afterward.

Token scopes

Name	API value
Allow read access for identity resources (users and groups)	`account-idm-read`
Allow write access for identity resources (users and groups)	`account-idm-write`
Allow read access for environment resources	`account-env-read`
Allow write access for environment resources	`account-env-write`
Allow read access for usage and consumption resources	`account-uac-read`
Allow write access for usage and consumption resources	`account-uac-write`
Allow IAM policy configuration for environments	`iam-policies-management` `iam:policies:read` `iam:policies:write` `iam:bindings:read` `iam:bindings:write` `iam:effective-permissions:read`

Request a token

After you create the OAuth2 client, request the bearer token from the Dynatrace SSO system via an API call.

POST	`https://sso.dynatrace.com/sso/oauth2/token`
Content type	`application/x-www-form-urlencoded`

Provide the following parameters in the request body. Be sure to URL-encode all values!

Parameter	Value
grant_type	`client_credentials`
client_id	`{your-Client-ID}`
client_secret	`{your-Client-secret}`
scope	A list of required scopes separated by a whitespace, for example `account-uac-read account-uac-write`. 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	`urn:dtaccount:{your-account-UUID}`

The response of the request contains the bearer token.

Authenticate

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/2b794097-8ad2-4b32-b923-0131da2eeddf/users \
  --header 'Authorization: Bearer abcdefjhij1234567890' \