Dynatrace User Management API Guide

Auth method: OAuth 2.0 client credentials (Bearer token)

Setup steps

1. Log in to Dynatrace and navigate to Account Management (account.dynatrace.com).
2. Go to Identity & Access Management > OAuth Clients.
3. Create an OAuth client and assign the required account-level scopes (e.g., account-idm-read, account-idm-write).
4. Note the client ID and client secret.
5. POST to https://sso.dynatrace.com/sso/oauth2/token with grant_type=client_credentials, client_id, client_secret, and scope to obtain a Bearer token.
6. Include the token as Authorization: Bearer on all Account Management API requests.

Required scopes

List users

• Method: GET
• URL: https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/users
• Watch out for: accountUuid is the Dynatrace account UUID, not an environment ID. Retrieve it from Account Management UI or the /accounts endpoint.

Request example

GET /iam/v1/accounts/{accountUuid}/users?pageSize=50
Authorization: Bearer <token>

Response example

{
  "items": [{"uid":"abc-123","email":"user@example.com","firstName":"Jane","lastName":"Doe","userStatus":"ACTIVE"}],
  "totalCount": 1,
  "nextPageKey": null
}

Get user

• Method: GET
• URL: https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/users/{userId}
• Watch out for: userId is the uid UUID, not the email address.

Request example

GET /iam/v1/accounts/{accountUuid}/users/abc-123
Authorization: Bearer <token>

Response example

{
  "uid": "abc-123",
  "email": "user@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "userStatus": "ACTIVE",
  "createdAt": "2024-01-10T08:00:00Z"
}

Create/invite user

• Method: POST
• URL: https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/users
• Watch out for: Creating a user sends an invitation email. User status is PENDING until they accept. SSO-provisioned users may bypass this flow.

Request example

POST /iam/v1/accounts/{accountUuid}/users
Content-Type: application/json
{
  "email": "newuser@example.com",
  "firstName": "John",
  "lastName": "Smith"
}

Response example

{
  "uid": "def-456",
  "email": "newuser@example.com",
  "userStatus": "PENDING"
}

Update user

• Method: PUT
• URL: https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/users/{userId}
• Watch out for: Full PUT replacement; omitting optional fields may clear them. Group membership is managed separately.

Request example

PUT /iam/v1/accounts/{accountUuid}/users/def-456
Content-Type: application/json
{
  "email": "newuser@example.com",
  "firstName": "Jonathan",
  "lastName": "Smith"
}

Response example

{
  "uid": "def-456",
  "email": "newuser@example.com",
  "firstName": "Jonathan",
  "lastName": "Smith",
  "userStatus": "PENDING"
}

Delete user

• Method: DELETE
• URL: https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/users/{userId}
• Watch out for: Deletion is immediate and permanent. Removes the user from all groups and revokes all environment access.

Request example

DELETE /iam/v1/accounts/{accountUuid}/users/def-456
Authorization: Bearer <token>

Response example

HTTP 204 No Content

List groups

• Method: GET
• URL: https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/groups
• Watch out for: Groups created via SCIM are marked with a managedBy field indicating SCIM; avoid mixing manual and SCIM group management.

Request example

GET /iam/v1/accounts/{accountUuid}/groups
Authorization: Bearer <token>

Response example

{
  "items": [{"groupId":"grp-001","name":"Admins","description":"Admin group"}],
  "totalCount": 1
}

Add users to group

• Method: POST
• URL: https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/groups/{groupId}/users
• Watch out for: Body is a JSON array of user UIDs, not an object. Passing email addresses will result in a 400 error.

Request example

POST /iam/v1/accounts/{accountUuid}/groups/grp-001/users
Content-Type: application/json
["abc-123", "def-456"]

Response example

HTTP 204 No Content

Remove user from group

• Method: DELETE
• URL: https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/groups/{groupId}/users/{userId}
• Watch out for: Removing a user from all groups does not deactivate the user account; a separate DELETE /users/{userId} call is required.

Request example

DELETE /iam/v1/accounts/{accountUuid}/groups/grp-001/users/abc-123
Authorization: Bearer <token>

Response example

HTTP 204 No Content

• Rate limits: Dynatrace Account Management API enforces rate limits per OAuth client. Exact numeric limits are not publicly documented; Dynatrace recommends implementing exponential back-off on HTTP 429 responses.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: On HTTP 429, inspect the Retry-After response header for the wait interval before retrying. Dynatrace does not publish a fixed requests-per-minute figure in public docs.
• Pagination method: token
• Default page size: 50
• Max page size: 500
• Pagination pointer: nextPageKey

• Webhooks available: No
• Webhook notes: Dynatrace Account Management API does not expose webhook or event-subscription endpoints for user lifecycle events (create, update, delete).
• Alternative event strategy: Poll the GET /users endpoint on a schedule to detect changes, or rely on SCIM push provisioning from an IdP (Okta, Entra ID) for real-time sync.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: SaaS Enterprise (DPS subscription)

• Endpoint: https://{your-environment-id}.live.dynatrace.com/api/v2/scim

• Supported operations: GET /Users – list users, GET /Users/{id} – get user, POST /Users – create user, PUT /Users/{id} – replace user, PATCH /Users/{id} – update user, DELETE /Users/{id} – delete user, GET /Groups – list groups, GET /Groups/{id} – get group, POST /Groups – create group, PUT /Groups/{id} – replace group, PATCH /Groups/{id} – update group members, DELETE /Groups/{id} – delete group, GET /ServiceProviderConfig, GET /Schemas, GET /ResourceTypes

Limitations:

• Requires SAML SSO to be configured and domain verification completed before SCIM can be enabled.
• SCIM token is generated in Account Management UI under Identity & Access Management > SCIM.
• Only one active SCIM token per environment; rotating the token invalidates the previous one immediately.
• SCIM provisioning manages users at the Dynatrace account level; environment-level permissions must still be assigned via groups.
• Groups managed by SCIM should not be modified manually in the Dynatrace UI to avoid sync conflicts.
• Supported IdPs with documented integration guides: Okta and Microsoft Entra ID (Azure AD). Google Workspace and OneLogin are not officially documented.
• SCIM user schema uses standard attributes (userName, name.givenName, name.familyName, emails, active); custom schema extensions are not documented.

Three workflows cover the majority of programmatic identity management needs.

First, user provisioning: POST to /accounts/{accountUuid}/users with email, firstName, and lastName to create the user (status returns as PENDING); then POST a JSON array of UIDs - not email addresses - to /groups/{groupId}/users to assign group membership.

Second, offboarding: resolve the user's uid via GET /users filtered by email, then DELETE /users/{userId}; deletion is immediate, permanent, and removes all environment access with no soft-delete option in the REST API. For deactivation without deletion, use SCIM PATCH with active=false instead.

Third, SCIM setup with Okta: SAML SSO and domain verification must be complete before SCIM can be enabled. only one SCIM token is active per environment at a time, and regenerating it breaks the Okta sync immediately until the new token is updated on the Okta side.

Provision a new user and assign to a group

1. Obtain an OAuth 2.0 Bearer token from https://sso.dynatrace.com/sso/oauth2/token using client credentials with account-idm-write scope.
2. POST to /iam/v1/accounts/{accountUuid}/users with email, firstName, lastName to create the user (returns uid, status PENDING).
3. POST to /iam/v1/accounts/{accountUuid}/groups/{groupId}/users with a JSON array containing the new user's uid to assign group membership.
4. Verify by GET /iam/v1/accounts/{accountUuid}/users/{uid} and confirm groups field includes the target groupId.

Watch out for: The user receives an invitation email and cannot access Dynatrace until they accept it, unless SAML SSO with JIT provisioning is active.

Deprovision a user (offboarding)

1. Obtain a Bearer token with account-idm-write scope.
2. GET /iam/v1/accounts/{accountUuid}/users to find the user's uid by email.
3. Optionally, remove the user from all groups via DELETE /iam/v1/accounts/{accountUuid}/groups/{groupId}/users/{userId} for each group.
4. DELETE /iam/v1/accounts/{accountUuid}/users/{userId} to permanently remove the user and revoke all access.

Watch out for: Deletion is permanent with no undo. If soft-deactivation is preferred, use SCIM PATCH with active=false instead.

Configure SCIM provisioning with Okta

1. Ensure SAML SSO is configured and domain verification is complete in Dynatrace Account Management.
2. In Dynatrace Account Management, navigate to Identity & Access Management > SCIM and generate a SCIM token.
3. In Okta, add the Dynatrace application from the Okta Integration Network and enable SCIM provisioning.
4. Set the SCIM base URL to https://{environment-id}.live.dynatrace.com/api/v2/scim and paste the SCIM token as the Bearer token.
5. Enable provisioning features: Push Users, Push Groups, Import Users.
6. Assign users and groups in Okta; Okta will push creates, updates, and deactivations to Dynatrace automatically.

Watch out for: Only one SCIM token is active at a time. Regenerating the token in Dynatrace immediately breaks the Okta sync until the new token is updated in Okta.

Several non-obvious behaviors create integration failures at runtime. The PUT /users/{userId} endpoint is a full replacement: omitting optional fields clears them, and group membership is managed on a separate endpoint entirely - it is not updated via the user PUT.

Pagination uses an opaque nextPageKey cursor token returned in the response body; numeric offset pagination is not supported, and the default page size is 50 with a maximum of 500.

Rate limit thresholds are not publicly documented; the API returns HTTP 429 with a Retry-After header, so exponential back-off with header inspection is required rather than a fixed retry interval.

Finally, SCIM and the Account Management API share the same user store: concurrent writes from both paths without coordination will produce sync conflicts, and groups marked managedBy: SCIM in the API response should not be modified manually in either the UI or the REST API.