Dynatrace Managed API: Cluster API v1 and v2, Environment API and the Settings schemas available

Dynatrace Managed API: Cluster API v1 and v2, Environment API, base URLs, tokens, permissions and how to list the Settings schemas of your version.
API Dynatrace Managed : Cluster API v1 et v2, Environment API et schémas Settings disponibles

You are automating a Managed cluster and every script starts with the same question: which URL do I call, with which token, and does this endpoint really exist on my version? The Dynatrace Managed API is not a single API but two families living side by side: the Cluster API, which drives the cluster from the Cluster Management Console (CMC), and the Environment API, which works inside one environment.

Mixing them up creates toil: a cluster token sent to an environment endpoint, a SaaS URL copied from a tutorial, a Settings schema that does not exist yet on your build. The result is 401s, 404s and automation pipelines that fail overnight.

The goal of this reference guide: know within minutes which API to call, with which token and permission, and how to list the Settings schemas actually available on your cluster. The content applies to Dynatrace Managed only; differences with SaaS are flagged.

The two families of the Dynatrace Managed API

The Managed documentation draws a clear line between two scopes. The Cluster API acts on the whole cluster, even when it hosts several environments. The Environment API acts on one environment, identified by its ID in the URL.

Criterion Cluster API (v1 and v2) Environment API (v1, v2, config v1)
Scope The whole cluster: nodes, environments, users, licence, cluster tokens One environment: entities, metrics, problems, Settings, environment tokens
Base URL https://{cluster}/api/cluster/v2/… and https://{cluster}/api/v1.0/onpremise/… https://{cluster}/e/{environment-id}/api/v2/…
Where to create the token CMC, Settings > API tokens, Cluster tokens section In the environment, Access Tokens page
Typical permissions ServiceProviderAPI, ClusterTokenManagement settings.read, apiTokens.write, etc.
Interactive docs CMC user menu, Cluster API v1 or Cluster API v2 The environment’s API explorer

For end-to-end administration automation (creating environments in bulk, managing users), see the tutorial on automating administration with the Cluster API. Here we focus on the map and the pitfalls.

Prerequisites

  • A Dynatrace Managed cluster and administrator access to the CMC.
  • A cluster token with the ServiceProviderAPI permission (reading and managing environments, nodes, users, licence).
  • An environment token with the settings.read scope to list schemas.
  • curl and jq on the machine calling the API.

Both tokens go in the Authorization: Api-Token … header. If a call is rejected, the guide on troubleshooting a Dynatrace API token covers 401, 403 and 404 diagnosis.

Step 1: create the right tokens

Cluster token

In the CMC, open Settings > API tokens, then in the Cluster tokens section select Generate token. The documented permissions for cluster configuration are:

Display name API value Use
Cluster token management ClusterTokenManagement Manage cluster tokens through the Tokens API
Service Provider API ServiceProviderAPI Cluster management operations (environments, users, nodes, licence)
Read settings settings.read Read cluster-level settings (API v2)
Write settings settings.write Write cluster-level settings (API v2)

Dynatrace recommends one token per purpose, with a single scope where possible: if it leaks, the blast radius stays small.

Environment token management token

The same page has an Environment token management tokens section. This token is used to create tokens inside a given environment through the API. It is only valid for 24 hours, because of its potential impact on every environment.

Environment token

In the environment, on the Access Tokens page, select Generate new token and tick settings.read. Copy it straight away: it will not be shown again.

Step 2: the Cluster API endpoint reference table

These are the endpoints used most often, all checked against the Managed documentation. They all require the ServiceProviderAPI permission, except tokens (ClusterTokenManagement).

Family Method and path Version
Environments GET / POST /api/cluster/v2/environments v2
Single environment GET / PUT / DELETE /api/cluster/v2/environments/{id} v2
Known nodes GET /api/v1.0/onpremise/cluster v1
Node configuration GET /api/v1.0/onpremise/cluster/configuration v1
Users GET /api/v1.0/onpremise/users v1
User groups GET /api/v1.0/onpremise/groups v1
Licence (export) GET /api/cluster/v2/license/consumption v2
Cluster tokens GET / POST /api/cluster/v2/tokens v2

Cluster API v1 also covers cluster maintenance, the internet proxy (including per data centre in high availability), the password policy, SSL certificates and triggering updates. v2 adds private Synthetic locations and nodes, user sessions, remote access and Log Monitoring status. The exact list depends on your build: the CMC’s interactive documentation is the source of truth.

A few useful details:

  • GET /api/cluster/v2/environments is paginated: pageSize (100 by default, 1000 at most), nextPageKey, sort (name, -name, creationDate…) and filter, for example name(prod).
  • POST /api/cluster/v2/environments?createToken=true also returns a token management token (apiTokens.read, apiTokens.write, TenantTokenManagement) usable in the new environment.
  • The licence export returns a ZIP file (application/octet-stream) and only works with classic licensing: otherwise you get a 422.

For per-environment quotas, see managing multiple environments and licence quotas in the CMC.

Step 3: call the Cluster API with curl

export DT_CLUSTER="https://managed.example.com"
export DT_CLUSTER_TOKEN="dt0c01.XXXX..."   # cluster token, ServiceProviderAPI

# List environments (name and ID), sorted by name
curl -s "$DT_CLUSTER/api/cluster/v2/environments?pageSize=100&sort=name" \
  -H "Authorization: Api-Token $DT_CLUSTER_TOKEN" \
  -H "accept: application/json" | jq '.environments[] | {id, name, state}'

# List known nodes and their version
curl -s "$DT_CLUSTER/api/v1.0/onpremise/cluster" \
  -H "Authorization: Api-Token $DT_CLUSTER_TOKEN" \
  | jq '.[] | {id, buildVersion, operationState}'

The second command returns, for each node, the id, buildVersion and operationState fields. It is the simplest way to know your cluster version before relying on a recent endpoint. The field names in the first response (environments, state) should be checked against your version in the CMC explorer.

Step 4: list the Settings schemas of your version

Settings 2.0 schemas change with every release. A schema documented for SaaS may not exist yet on your cluster. Do not guess: ask the environment for the list.

export DT_ENV="https://managed.example.com/e/abc12345-6789"
export DT_ENV_TOKEN="dt0c01.YYYY..."   # environment token, settings.read

curl -s "$DT_ENV/api/v2/settings/schemas?fields=schemaId,displayName,latestSchemaVersion,maturity" \
  -H "Authorization: Api-Token $DT_ENV_TOKEN" \
  | jq -r '.items[] | [.schemaId, .latestSchemaVersion, .maturity] | @tsv' | sort

The response is a SchemaList object: an items array and a totalCount counter. The fields parameter accepts schemaId, displayName, maturity, latestSchemaVersion, multiObject, ordered and ownerBasedAccessControl. The maturity field is PREVIEW, EARLY_ADOPTER or GENERAL_AVAILABILITY: for production automation, prefer GA schemas.

Example to check that a schema exists before using it in Terraform or Monaco:

curl -s "$DT_ENV/api/v2/settings/schemas?fields=schemaId" \
  -H "Authorization: Api-Token $DT_ENV_TOKEN" \
  | jq -e '.items[] | select(.schemaId == "builtin:alerting.profile")' \
  && echo "schema available" || echo "schema missing on this version"

Next, GET /api/v2/settings/objects?schemaIds=… (scope settings.read) lists the existing objects for that schema. If the call goes through an ActiveGate, the URL becomes https://{activegate}:9999/e/{environment-id}/api/v2/….

What does not exist in Managed

Many published examples target the SaaS platform. Before copying a call, check that it does not depend on one of these building blocks, which Managed lacks:

  • the platform APIs (URLs under *.apps.dynatrace.com/platform/…), platform tokens and the related OAuth authentication;
  • Grail and DQL queries through the storage API;
  • AppEngine, Dynatrace Apps, platform Workflows and the new-generation Notebooks or Dashboards;
  • the Account Management API (api.dynatrace.com/iam/v1/…): in Managed, users and groups go through Cluster API v1.

The authentication page of the Managed documentation itself points to the list of features unavailable in Managed for platform tokens. On Managed, stick to Environment API v1 and v2, configuration API v1 and the Cluster API.

How to check that it works

  1. GET /api/v1.0/onpremise/cluster returns 200 and the node list: the cluster token and URL are correct.
  2. GET /api/cluster/v2/environments returns your environments: the ServiceProviderAPI permission is present.
  3. GET /e/{id}/api/v2/settings/schemas returns a totalCount above zero: the environment token carries settings.read.
  4. A cluster token sent to /e/{id}/api/v2/… should fail: that is expected, the two token families are separate.

Best practices

  • One token, one purpose: one ServiceProviderAPI token for inventory, another for token management, each with an expiry date.
  • Version the schema list: export it after every cluster update and diff it with the previous one. New schemas appear silently.
  • Respect rate limits: throttle loops over all environments, especially in multi-tenant setups.
  • Centralise secrets: never put a token in a repository or in CI pipeline logs.
  • Access rights: align groups created through the API with the model described in users, groups and permissions in Managed.

Frequently asked questions

What is the difference between Cluster API v1 and v2?

They are two complementary sets of endpoints, both active. v1 (/api/v1.0/onpremise/…) covers nodes, maintenance, proxy, users, groups and certificates. v2 (/api/cluster/v2/…) covers environments, tokens, licence and Synthetic. You use both depending on the object you target.

Can an environment token call the Cluster API?

No. The Cluster API requires a cluster token created in the CMC. Conversely, a cluster token is not meant for querying an environment’s entities or metrics.

How do I know whether a Settings schema from the SaaS docs exists on my cluster?

Call GET /e/{id}/api/v2/settings/schemas and look for the schemaId. If it is missing, it may arrive with a later cluster version; check the Managed release notes.

Conclusion

The Dynatrace Managed API comes down to three habits: the Cluster API for the cluster, with a token from the CMC; the Environment API under /e/{id}/api/v2 for everything else; and the Settings schema list queried on your own version before any automation. With the reference table above and the curl calls, your scripts stop guessing and your cluster updates become predictable.

Official reference: Cluster API (Managed documentation) and Settings API, list of schemas.

span.observer is an independent community blog, not affiliated with Dynatrace LLC. Dynatrace is a trademark of its owner. Endpoints, permissions and screen names change between versions: check them in the official documentation for your cluster.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
API Dynatrace SaaS : la carte complète des API et des schémas Settings 2.0

Dynatrace SaaS API: the complete map of APIs and Settings 2.0 schemas

Next Post
Dashboard Dynatrace SaaS : construire des tableaux de bord DQL sur Grail, avec 3 exemples complets

Dynatrace SaaS dashboard: building DQL dashboards on Grail, with 3 complete examples

Related Posts