Upgrade from Classic access tokens to platform tokens
- Latest Dynatrace
- Upgrade guide
Dynatrace Classic authenticates API calls with Classic access tokens, managed through the Environment API v2/apiTokens endpoint. Latest Dynatrace introduces platform tokens as the recommended mechanism for programmatic access: They're user-bounded, managed centrally in Account Management, and governed at the account level.
This guide covers the full upgrade from Classic access tokens to platform tokens.
This upgrade affects every integration, script, CI/CD pipeline, and third-party tool that currently authenticates with a Classic access token.
Why upgrade?
Classic access tokens encouraged creating tokens with broad scopes, had no required association to a specific user or service account, and had no practical upper limit per environment, which often led to token sprawl and unclear ownership. Platform tokens close these gaps:
- User-bounded access: Every platform token belongs to a specific user or service user and operates only within that user's permissions. A scope selection can't grant access beyond what the user is allowed to do.
- Account-level governance: Account administrators can view and manage all tokens across an account, deactivate token creation entirely, or deactivate and delete individual tokens.
- Built-in rotation: Account Management includes a first-class rotation operation with a configurable overlap window, which makes regular credential rotation practical.
- Single-account scope: A platform token is scoped to one account and can't access others, limiting the blast radius if a token is compromised.
Compare Classic access tokens and platform tokens
| Classic access token | Platform token |
|---|---|
Created via | Created in Account Management |
Scoped to a Dynatrace environment | Scoped to an account, optionally narrowed to specific environments |
Owned by the environment | Owned by a user or service user |
Unlimited per environment | 50 per user, 100 per service user, per account (see Platform tokens) |
Base URL: | Base URL: |
|
|
Managed via the Environment API | Managed via Account Management |
What will you do?
You'll upgrade every integration that authenticates with a Classic access token. First, you'll build an inventory of your existing Classic access tokens and classify them by usage. Then you replace each active integration with a platform token, validate it, and decommission the Classic access tokens you no longer need.
Before you begin
Prerequisites
- A Classic access token with the
apiTokens.readscope (to export the inventory) and theapiTokens.writescope (to deactivate and delete tokens). See Access tokens classic. - Access to Account Management to create platform tokens. Every user can create their own; to manage platform tokens through the Account Management API, you need the
platform-token:tokens:managescope. - To assign platform tokens to a service user (recommended for automation), an account administrator must grant your group the
iam:service-users:usepermission, optionally scoped to specific service users usingiam:service-user-email. See Platform tokens.
New concepts
- The authorization header changes from
Authorization: Api-Token <your-classic-access-token>for Classic access tokens toAuthorization: Bearer <your-platform-token>for platform tokens. - Ownership changes from the environment to a user: A Classic access token belongs to the environment. In contrast, a platform token belongs to a specific user or service user and works only within that user's permissions.
Environment states
Where you manage Classic access tokens depends on your environment state. Platform tokens are always managed through the Account Management API (https://api.dynatrace.com), which is available in all states.
-
Hybrid: Both Classic and Latest functionality are available.
Classic access token management remains. It additionally becomes available via the
.appsdomain, and platform tokens are available alongside Classic access tokens.When an environment enters the Hybrid state, the
v2/apiTokensendpoint moves from the.liveto the.appsbase URL. Update any scripts or configurations that hardcode.liveURLs before the transition. -
Latest: Only platform tokens are available. Classic access tokens don't exist, and
v2/apiTokensisn't available.
Endpoint mapping
Each Classic v2/apiTokens operation maps to a platform-token operation in the Account Management API. All platform token management operations require the platform-token:tokens:manage scope.
Show the endpoint mapping
| Operation | Classic access tokens (v2/apiTokens) | Platform tokens (Account Management API) |
|---|---|---|
List all tokens |
|
|
Get a token by ID |
| No direct equivalent. Use the list endpoint with |
Find a token by secret |
| Not available. Platform tokens don't support lookup by secret value |
Create a token |
|
|
Activate or deactivate a token |
|
|
Update expiration date |
|
|
Delete a token |
|
|
How to upgrade
Steps
1. Export an inventory of your Classic access tokens
Export a complete snapshot of your existing Classic access tokens before making any changes. This baseline lets you measure progress, preserves point-in-time metadata (such as last-used dates, scopes, and expiry), and provides an audit trail.
-
Call the
v2/apiTokensendpoint with the metadata fields you need, using the base URL for your environment.curl -s \-H "Authorization: Api-Token <your-classic-access-token>" \"https://{your-environment-id}.live.dynatrace.com/api/v2/apiTokens?fields=%2BlastUsedDate,%2BlastUsedIpAddress,%2BexpirationDate,%2Bscopes"This call requires the
apiTokens.readscope. Responses are paged, so keep requesting with?nextPageKey=<value>until the endpoint returns nonextPageKey. For the full endpoint reference, see Access tokens API - GET all tokens. -
Store the export in an access-controlled location, such as a restricted repository, a private page, or an upgrade ticket attachment, and record that location. The export contains token metadata, including IP addresses (
lastUsedIpAddress), which may be personal data. Keep access to it restricted and apply your organization's data-handling policy for personal data.
2. Classify each Classic access token
Classify every Classic access token before you act. Don't delete a token on the assumption that it's unused, because it might be used in a periodic or seasonal workflow.
The API doesn't enforce unique token names, so that an environment can contain multiple tokens with the same name. Always track, quarantine, and delete tokens by their unique ID, never by name. Names are for human readability only.
Use the following guide:
| Classification | Signal | Recommended action |
|---|---|---|
Actively used |
| Upgrade first. Highest impact if blocked. |
Rarely used |
| Find the owner, schedule upgrade. |
Batch or periodic |
| Apply a grace period (at least one full job cycle) before acting. |
Unused or orphaned | No recorded | Quarantine, then delete. |
Some tokens serve infrequent but legitimate tasks, such as quarterly reports, annual audit exports, or fortnightly batch jobs. Before treating a token as inactive, cross-reference its lastUsedDate with the known schedule of the integration it serves. Scopes related to reporting, data export, or archival are a signal of periodic use. Treat the 30/180-day thresholds as a starting point, not a rule.
For richer classification—which endpoints a token calls, how often, and from where—query the Dynatrace audit logs with DQL in 
Notebooks:
fetch dt.system.events| filter event.kind == "AUDIT_EVENT"| filter event.provider == "CLASSIC_API"| summarize count(), by:{authentication.token, endpoint}
authentication.tokenis the public portion of the token, which you can match to your inventory.- Grouping the results by
endpointshows how often and how regularly each token calls a given endpoint, which helps you spot periodic or batch use.
Querying dt.system.events requires access to Grail and the appropriate query permissions. How far back you can look depends on your Grail retention configuration.
3. Replace each integration with a platform token
For each Classic access token classified as actively used, or rarely used with a confirmed owner, replace it with a platform token:
-
Create a platform token in Account Management, assigned to a service user for automation, with the minimum scopes the integration needs. To see which scopes map to which endpoints, use the Dynatrace API explorer your environment offers under this URL:
https://<your-environment>.apps.dynatrace.com/platform/swagger-ui/index.html.- Go to My platform tokens.
- Create a platform token. For the full procedure, see Platform tokens.
-
Find every place the old token is stored: secrets managers, CI/CD variables, Kubernetes secrets, config files, and scheduled scripts.
-
Replace the stored value with the new platform token.
-
Update the authorization header from
Authorization: Api-Token <your-classic-access-token>toAuthorization: Bearer <your-platform-token>.For example:
curl -s \-H "Authorization: Bearer <your-platform-token>" \"https://{your-environment-id}.apps.dynatrace.com/platform/storage/logs/v1/export" -
Run the integration end-to-end against the platform token before removing the Classic access token.
Don't delete the old Classic access token until you can confirm the platform token works. If you get a 403, see Troubleshoot issues.
4. Validate the platform token
Confirm all of the following before removing the Classic access token:
- The platform token works end-to-end, with no HTTP 401 or 403 responses.
- The token carries the minimum required scopes, and the assigned user or service user has the matching Dynatrace permissions.
- You have removed the old Classic access token from every known location—secrets managers, CI/CD variables, Kubernetes secrets, config files, scripts, source code, and documentation.
5. Decommission the Classic access tokens
Once the platform token works, retire the Classic access token:
-
Deactivate the Classic access token. You can reactivate a token that was deactivated due to a missing dependency, so deactivating it first is safer than deleting it outright.
curl -s -X PUT \-H "Authorization: Api-Token <your-classic-access-token>" \-H "Content-Type: application/json" \-d '{"revoked": true}' \"https://{your-environment-id}.live.dynatrace.com/api/v2/apiTokens/{id}"This call requires the
apiTokens.writescope. See Access tokens API - PUT a token. -
Wait one full business or job cycle to confirm nothing still depends on the token.
-
Delete the Classic access token. Deletion is permanent.
Delete tokens by their unique ID, never by name. Token names aren't unique.
curl -s -X DELETE \-H "Authorization: Api-Token <your-classic-access-token>" \"https://{your-environment-id}.live.dynatrace.com/api/v2/apiTokens/{id}"This call requires the
apiTokens.writescope. See Access tokens API - DELETE a token. -
Leave your last Classic access token in place for now. Removing it needs a different approach, covered in the next step.
6. Remove the last Classic access token
The v2/apiTokens API requires a Classic access token to authenticate, which creates a circular dependency when you delete your final token. There's no Classic access token left to authorize the deletion. Handle it one of two ways.
Self-removal
- Keep one Classic access token that has the
apiTokens.writescope as your final cleanup token, and remove all the others. - Use the cleanup token to delete itself. The
DELETE /api/v2/apiTokens/{id}endpoint accepts the token's own ID.
Platform token on .apps
- In a Hybrid environment, create a platform token with the appropriate scope.
- Using that platform token, call
DELETE /api/v2/apiTokens/{id}on the.appsdomain to delete each remaining Classic access token, including the last one.
Plan this sequence before you start, so you don't delete every token with the apiTokens.write scope before cleanup is complete.
7. Confirm the upgrade is complete
Your upgrade is complete when:
- You've saved the inventory baseline in an access-controlled location.
- Every remaining Classic access token has an identified owner.
- You've defined a cleanup policy, for example, to remove Classic access tokens unused for 180 or more days, with a documented exception process for confirmed batch workflows.
- You've defined a rotation schedule for the new platform tokens, using the built-in rotate function with an overlap window. See Platform tokens.
Roll back an upgrade
If an integration breaks after switching to a platform token:
- Reactivate the old Classic access token, if you have deactivated but not yet deleted it, to restore service immediately.
- Revert the integration to the Classic access token while you diagnose.
- Find the root cause (see Troubleshoot issues) and retry the upgrade.
Troubleshoot issues
If an upgraded integration fails after switching to a platform token, check these common issues.
Why does my platform token return HTTP 403?
A 403 means either the token lacks the required scope for the endpoint, or the user or service user the token belongs to lacks the required Dynatrace permission. Both must be in place, since a scope can't grant access beyond what the assigned user is allowed to do.
Expired tokens also return 403. Check the token's expiration date. Expired tokens remain in the token list until explicitly deleted—use the built-in rotate function to replace expiring tokens before they lapse. See Platform tokens.
Why does a deactivated platform token still authenticate?
Deactivating a platform token takes effect immediately, but propagation across all platform services can take up to five minutes. During that window, some services may still accept the token.