Try it free

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 replaces them with platform tokens: credentials bound to a specific user or service user, managed centrally in Account Management, and governed at the account level.

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 broad scopes, had no required association to a specific user or service account, and had no practical upper limit per environment. The result was often 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 assigned user is allowed to do.
  • Account-level governance: Account administrators can view and manage all tokens across an account, disable token creation entirely, or disable and delete individual tokens.
  • Built-in rotation: Account Management includes a rotate 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 be used to access other accounts, limiting the impact if a token is compromised.

Compare Classic access tokens and platform tokens

Classic access tokenPlatform token
Created via POST /api/v2/apiTokens or in Access tokensCreated in Account Management
Scoped to a Dynatrace environmentScoped to an account, optionally narrowed to specific environments
Owned by the environmentOwned by a user or service user
Unlimited per environment50 per user, 100 per service user, per account (see Platform tokens)
Base URL: .live.dynatrace.comBase URL: api.dynatrace.com (Account Management API)
Authorization: Api-Token <your-classic-access-token>Authorization: Bearer <your-platform-token>
Managed via the Environment APIManaged via Account Management

What will you do?

In this upgrade guide, you'll:

  1. Export an inventory of your existing Classic access tokens.
  2. Classify each one by usage pattern.
  3. Create platform token replacements for active integrations.
  4. Validate each replacement.
  5. Decommission the Classic access tokens you no longer need.
  6. Remove the last Classic access token.

Before you begin

Prerequisites

To complete this upgrade guide, you need:

  • If you have access to Account Management, you can create platform tokens. To manage platform tokens through the Account Management API, your Dynatrace user needs the platform-token:tokens:manage scope. See Platform tokens API - GET all a platform token.
  • For automated integrations, the iam:service-users:use permission (optionally scoped with iam:service-user-email) granted to the relevant group by an account administrator, to assign tokens to service users. See Platform tokens.
  • A Classic access token with the apiTokens.read scope to export the inventory, and the apiTokens.write scope to disable and delete tokens.

Prior knowledge

  • Familiarity with where your integrations store their Classic access tokens: secrets managers, CI/CD pipeline variables, Kubernetes secrets, configuration files, or scheduled scripts.

Breaking changes

ChangeRequired action
v2/apiTokens moves to the .apps base URL in hybrid environmentsUpdate any scripts, SDK configurations, or documentation that hardcode the .live URL before your environment enters the hybrid state.
Authentication header format changesReplace Authorization: Api-Token <your-classic-access-token> with Authorization: Bearer <your-platform-token> in every upgraded integration.
v2/apiTokens isn't available in latest environmentsComplete the upgrade before your environment reaches the latest state. There's no Classic access token management after that point.

New concepts

Where you manage tokens depends on the token type.

  • For platform tokens, use Account Management or the Account Management API, in all environment states. Some operations are available in only one of them.
  • For Classic access tokens, the place depends on your environment state.
Classic environment

Classic access tokens only, managed through v2/apiTokens on the .live domain.

Hybrid environment

Both Classic and latest functionality are available. Classic access token management remains, but moves to the .apps domain, and platform tokens are available alongside Classic access tokens. Most environments moving to Latest Dynatrace functionality run in the hybrid state.

Latest environment

Platform tokens only. Classic access tokens don't exist, and v2/apiTokens isn't available.

Service user

An account-level identity used to run automated integrations, separate from any individual's personal account. Platform tokens assigned to a service user don't count against a person's token limit.

Endpoint mapping

Each Classic v2/apiTokens operation maps to a platform token operation in the Account Management API.

OperationClassic access tokens (v2/apiTokens)Platform tokens (Account Management API)
List all tokensGET https://{env-id}.live.dynatrace.com/api/v2/apiTokensGET https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/platform-tokens
Get a token by IDGET https://{env-id}.live.dynatrace.com/api/v2/apiTokens/{id}No direct equivalent. Use the list endpoint with searchTerm={tokenId} to filter
Find a token by secretPOST https://{env-id}.live.dynatrace.com/api/v2/apiTokens/lookupNot available. Platform tokens don't support lookup by secret value
Create a tokenPOST https://{env-id}.live.dynatrace.com/api/v2/apiTokensPOST https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/platform-tokens
Enable or disable a tokenPUT https://{env-id}.live.dynatrace.com/api/v2/apiTokens/{id} (set revoked)PUT https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/platform-tokens/{platformTokenId}/status
Update expiration datePUT https://{env-id}.live.dynatrace.com/api/v2/apiTokens/{id}PUT https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/platform-tokens/{platformTokenId}/expiration-date
Delete a tokenDELETE https://{env-id}.live.dynatrace.com/api/v2/apiTokens/{id}DELETE https://api.dynatrace.com/iam/v1/accounts/{accountUuid}/platform-tokens/{platformTokenId}

How to upgrade

Step 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 (last-used dates, scopes, and expiry), and gives you an audit trail for compliance review.

The Dynatrace API doesn't enforce unique names for Classic access tokens, so an environment can contain multiple tokens with the same name. Always use the token's unique ID, not its name, as the stable reference for classification, upgrade tracking, and deletion.

  1. Call the v2/apiTokens endpoint 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"
    curl -s \
      -H "Authorization: Api-Token <your-classic-access-token>" \
      "https://{your-environment-id}.apps.dynatrace.com/api/v2/apiTokens?fields=%2BlastUsedDate,%2BlastUsedIpAddress,%2BexpirationDate,%2Bscopes"

    This call requires the apiTokens.read scope. Responses are paged, so keep requesting with ?nextPageKey=<value> until the endpoint returns no nextPageKey. For the full endpoint reference, see Access tokens API - GET all tokens.

  2. Store the export in an access-controlled location, such as a restricted repository, a private page, or an attachment on your upgrade ticket, 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.

You now have a complete, timestamped baseline of every Classic access token in the environment.

Step 2: Classify each Classic access token

Classify every Classic access token before you act. A token that looks idle may still serve a periodic or seasonal workflow, so don't delete it until you've confirmed what it does.

Use the lastUsedDate from your inventory:

ClassificationSignalRecommended action
Actively usedlastUsedDate within the last 30 daysUpgrade first. Highest impact if blocked.
Rarely usedlastUsedDate between 30 and 180 days agoFind the owner, then schedule the upgrade.
Batch or periodiclastUsedDate beyond the threshold, but known as a scheduled jobApply a grace period of at least one full job cycle before acting.
Unused or orphanedNo recorded lastUsedDate, or an old token with no identified ownerQuarantine, then delete.

The 30-day/180-day thresholds are a starting point, not a rule: adapt them to your environment. Some tokens serve infrequent but legitimate tasks (quarterly reports, annual audit exports, biweekly batch jobs), so cross-reference lastUsedDate against the known schedule of the integration before treating a token as inactive. Scopes related to reporting, data export, or archival are a signal of periodic use.

For a richer view—which endpoints a token calls, how often, and from where—query the audit logs with DQL in Notebooks Notebooks:

fetch dt.system.events
| filter event.kind == "AUDIT_EVENT"
| filter event.provider == "CLASSIC_API"
| summarize count(), by:{authentication.token, endpoint}
  • authentication.token is the public portion of the token, which you can match to your inventory.
  • Grouping by endpoint shows how often 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.

Step 3: Create platform tokens for active integrations

For each Classic access token classified as actively used, or rarely used with a confirmed owner, create a platform token replacement.

Create the platform token in Account Management, not in the environment's settings or API configuration.

  1. Go to My platform tokens.
  2. Select Platform token and specify a token name, an expiration date, and the account. Either check Apply to account or select an environment from the Select environments dropdown.
  3. Choose whether to generate the token for yourself or for a service user you have access to.
  4. Select the minimum token scopes the integration needs.
  5. Select Generate, then copy the token value immediately—it's shown only once.

For the full procedure, see Platform tokens. To see which scopes map to which endpoints, use the Dynatrace API explorer in your environment: https://{your-environment-id}.apps.dynatrace.com/platform/swagger-ui/index.html.

For automated integrations, assign the token to a service user rather than your personal account. A service-user token keeps automation credentials separate from your personal limit of 50 tokens.

Replace the token in each integration.

  1. Identify every location where the old token is stored: secrets managers, CI/CD pipeline variables, Kubernetes secrets, application configuration files, and scheduled scripts.
  2. Update each location with the new platform token value.
  3. Update the authorization header from Authorization: Api-Token <your-classic-access-token> to Authorization: Bearer <your-platform-token>. See Platform tokens.
  4. Run the integration end-to-end to confirm it works before decommissioning the old token.

Don't delete the old Classic access token until you confirm the platform token works. If you get a 403, see Why does my platform token return HTTP 403?.

Each upgraded integration now authenticates with a platform token scoped to a user or service user, instead of an environment-wide Classic access token.

Step 4: Validate the platform token

For each upgraded integration, confirm the following before removing the Classic access token.

  • Check that the platform token works end-to-end, with no HTTP 401 or 403 responses.
  • Confirm the platform token has the minimum required scopes, and that the underlying user or service user has the required permissions. If it doesn't, see Why does my platform token return HTTP 403?.
  • Remove the old Classic access token from every known location: secrets managers, CI/CD variables, Kubernetes secrets, configuration files, scripts, source code, and documentation.

Step 5: Decommission the Classic access tokens

Once the platform token works, retire the Classic access token.

  1. Disable the Classic access token. A disabled token can be re-enabled if you missed a dependency, so disabling 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}"
    curl -s -X PUT \
      -H "Authorization: Api-Token <your-classic-access-token>" \
      -H "Content-Type: application/json" \
      -d '{"revoked": true}' \
      "https://{your-environment-id}.apps.dynatrace.com/api/v2/apiTokens/{id}"

    This call requires the apiTokens.write scope. See Access tokens API - PUT a token.

  2. Wait at least one full business or job cycle to confirm that nothing still depends on the token.

  3. Delete the Classic access token by its unique ID, never by name. Deletion is permanent.

    curl -s -X DELETE \
      -H "Authorization: Api-Token <your-classic-access-token>" \
      "https://{your-environment-id}.live.dynatrace.com/api/v2/apiTokens/{id}"
    curl -s -X DELETE \
      -H "Authorization: Api-Token <your-classic-access-token>" \
      "https://{your-environment-id}.apps.dynatrace.com/api/v2/apiTokens/{id}"

    This call requires the apiTokens.write scope. See Access tokens API - DELETE a token.

  4. Leave your last Classic access token in place for now. Removing it needs a different approach, covered in the next step.

Step 6: Remove the last Classic access token

When you delete your last Classic access token, you can either use the token itself (if it has the apiTokens.write scope) or a new platform token.

Use the Classic access token to delete itself:

  1. Keep one Classic access token that has the apiTokens.write scope as your final cleanup token, and remove all the others.
  2. Use the cleanup token to delete itself. The DELETE /api/v2/apiTokens/{id} endpoint accepts the token's own ID.

Use a new platform token to delete the Classic access token:

  1. In a hybrid environment, create a platform token with the appropriate scope.
  2. Using that platform token, call DELETE /api/v2/apiTokens/{id} on the .apps domain to delete each remaining Classic access token, including the last one.

Upgrade completed

Your upgrade is complete when:

  • All active integrations authenticate with platform tokens.
  • Classic access tokens are disabled and removed, and the inventory baseline is saved in an access-controlled location.
  • 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.

Account administrators can now manage every token from Account Management, with rotation and per-token governance available across the account.

FAQ

Why does my platform token return HTTP 403?

A 403 means one of two things: the token doesn't have the required scope for the endpoint being called, or the user or service user it's assigned to doesn't have the required Dynatrace permissions. Both must be in place, because a scope selection 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, so use the rotate function in Account Management to replace expiring tokens before they lapse. See Platform tokens.

I disabled a platform token, but it still authenticated. Why?

Disabling a platform token is recorded immediately, but propagation across all platform services can take up to five minutes. During that window, some services may still accept the token.

What if an integration breaks after I switch to a platform token?

If an integration breaks after you switch to a platform token:

  1. Re-enable the old Classic access token, if you disabled but didn't yet delete it, to restore service immediately. If you already deleted it, this can't be undone, and you need to create a working platform token instead.
  2. Revert the integration to the Classic access token while you diagnose. Classic access tokens and platform tokens can run side by side—see Validate the platform token.
  3. Find the root cause, then retry the upgrade.

Related topics

  • Tokens and OAuth clients
  • Platform tokens
  • Access tokens (Dynatrace Classic)
  • Tokens and oauth client concepts
  • Dynatrace API - Tokens and authentication
Related tags
Dynatrace Platform