Best practices for upgrading App Observability API endpoints

Latest Dynatrace
Best practices
Published Aug 24, 2026

Classic API tokens use broad, coarse-grained scopes that are difficult to audit. Latest Dynatrace uses platform tokens and OAuth clients with capability-based scoping for improved security and traceability. For Phase 3 environments, classic API token creation is disabled; all new integrations must use platform tokens. Before opting into Phase 3, audit all classic API token usage and migrate any automation that calls blocked endpoints. These best practices help you plan and execute that migration.

Audit classic API token usage before Phase 3 opt-in

Before opting into Phase 3, perform a complete audit of all classic API tokens and their active endpoints. Phase 3 disables access to blocked endpoints and prevents creation of new classic API tokens.

For each classic API token, document:

Scopes assigned: what permissions the token carries
Owner or integration: which team, script, pipeline, or third-party tool uses the token
Active endpoints: which classic API endpoints the token calls (use API access logs as a secondary signal)
Latest Dynatrace equivalent: the corresponding platform API endpoint for each classic endpoint in use

Build a migration list in the format: token → endpoint → latest equivalent → responsible team. Do not revoke tokens before confirming all consumers are identified. Classic tokens used by undocumented scripts or third-party tools break silently when revoked without warning.

Understand BLOCK, FROZEN, and ALT endpoint dispositions

Every classic API endpoint in Phase 3 falls into one of three categories:

Category	Meaning	Action required
BLOCK	Endpoint disabled entirely; the feature is removed or replaced by a Latest Dynatrace alternative	Must be migrated before opting into Phase 3
FROZEN	Endpoint remains accessible; existing classic API tokens still work; new integrations require platform tokens	Existing tokens work; new integrations must use OAuth
ALT	Endpoint is deprecated; the same data is accessible through an existing platform service such as Settings API or DQL	Existing tokens work; migration is recommended

Key blocked endpoints for App Observability that require migration before Phase 3:

config/v1/calculatedMetrics/service: migrate to OpenPipeline metric extraction using the Calculated service metrics upgrade guide
config/v1/service/detectionRules/*: migrate to Settings 2.0 API
config/v1/service/failureDetection/*: migrate to Settings 2.0 API

Key frozen endpoints that continue to work with classic tokens but require platform tokens for new integrations:

v2/otlp: requires OAuth scope openTelemetryTrace.ingest for new integrations
v2/logs/ingest: requires OAuth scope logs.ingest for new integrations
config/v1/service/customServices: new IAM permission required (schema ID builtin:settings.custom-service-detection)
config/v1/service/requestAttributes: new IAM permission required (schema ID builtin:request-attributes)
config/v1/service/requestNaming: new IAM permission required (schema ID builtin:request-naming)

Migrate BLOCKED endpoints before opting into Phase 3

Any automation that calls a blocked endpoint will stop working immediately after Phase 3 opt-in. Prioritize migrating blocked endpoint consumers before initiating the Phase 3 transition.

To migrate each blocked endpoint

Identify the replacement endpoint or platform service from the endpoint disposition table.
Update the automation, script, or pipeline to call the replacement.
Validate that the replacement produces equivalent output.
Confirm the classic endpoint is no longer called in API access logs.

Keep a migration checklist for blocked endpoints and confirm all items are resolved before scheduling Phase 3 opt-in. One missed blocked endpoint that powers a critical integration can cause an outage after opt-in.

Create OAuth clients with minimum required scopes

For each integration or team that needs access to Latest Dynatrace platform APIs, create a dedicated OAuth client with the minimum scopes required for the specific endpoints the integration calls.

To create an OAuth client

Open Account Management in your Dynatrace environment.
Create a new OAuth client.
Assign only the scopes required by the integration; refer to the endpoint documentation for the exact scope name.
Share the client credentials securely with the owning team or pipeline.

Avoid creating a single shared OAuth client for multiple integrations or teams. Separate OAuth clients per integration make it easier to rotate credentials, audit access, and revoke specific integrations without affecting others.

Overly broad OAuth client scopes reduce the security benefit of migrating from classic tokens. Map the minimum required scope for each integration before creating the OAuth client; do not copy the broad scope pattern of classic API tokens.

Start CI/CD pipeline migration early

CI/CD pipelines and automation scripts are the most common consumers of classic API tokens and the most time-consuming to migrate, because they often require coordination with teams that own the pipeline infrastructure. Start this migration early in the upgrade process.

For each CI/CD pipeline that calls classic Dynatrace APIs

Identify the pipeline owner and notify them of the migration requirement.
Provide the endpoint mapping from classic to Latest Dynatrace platform API.
Coordinate the OAuth client credential deployment; pipeline owners need a secure way to inject the new credentials into their CI/CD environment.
Test the updated pipeline in a non-production environment before promoting to production.
Monitor API access logs to confirm the pipeline has fully switched to the new endpoint.

Third-party tool vendors may need time to update their Dynatrace integration configurations. Contact vendors early to understand their timeline and whether their tool already supports platform tokens.

Ready for more?

Return to Upgrade your API integrations and tokens to continue your upgrade.