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
ServiceProviderAPIpermission (reading and managing environments, nodes, users, licence). - An environment token with the
settings.readscope to list schemas. curlandjqon 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/environmentsis paginated:pageSize(100 by default, 1000 at most),nextPageKey,sort(name,-name,creationDate…) andfilter, for examplename(prod).POST /api/cluster/v2/environments?createToken=truealso 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
GET /api/v1.0/onpremise/clusterreturns 200 and the node list: the cluster token and URL are correct.GET /api/cluster/v2/environmentsreturns your environments: theServiceProviderAPIpermission is present.GET /e/{id}/api/v2/settings/schemasreturns atotalCountabove zero: the environment token carriessettings.read.- 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
ServiceProviderAPItoken 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.