Try it free

Upgrade credential vault access from Classic to Latest Dynatrace

  • Latest Dynatrace
  • How-to guide
  • Published Nov 02, 2026

Latest Dynatrace uses the new credential vault API and SDK. With this change, credential vault access uses dedicated permissions like the rest of the platform, instead of the broad Classic environment:roles:viewer role.

This change affects everything that reads stored credentials:

  • Run JavaScript tasks in workflows, and JavaScript code in Dashboards Dashboards and Notebooks Notebooks: update the code and permissions at any time before you move to the Latest Dynatrace, and test them right away.
  • HTTP request tasks in workflows: no change to the task, but the workflow actor needs permissions before you move to the Latest Dynatrace.

What changes

The following table compares Classic and Latest Dynatrace for credential vault access.

ClassicLatest Dynatrace
API endpoint/api/v2/credentials/platform/credential-vault/v1/entries
IAM permissionenvironment:roles:viewercredential-vault:entries:read
Workflows authorization setting (non-service-user actors)environment-api:credentials:readcredential-vault:entries:read
SDK clientcredentialVaultClientcredentialVaultEntriesClient in @dynatrace-sdk/client-credential-vault (v1.1.0+)
Entry ID prefixCREDENTIALS_VAULT-CREDENTIAL_VAULT_ENTRY-

For the IAM permission, the default policies Standard User, Pro User, and Admin User include credential-vault:entries:read. If your users and service users get their permissions through one of these policies, you don't need to change anything. If they use custom policies, make sure those policies include credential-vault:entries:read.

Code that creates, updates, or deletes credential vault entries also needs credential-vault:entries:write.

Every credential vault entry already has a Classic ID and a new Smartscape ID, and both work with the new API and SDK. You don't need to update credential references in monitors, workflows, dashboards, or notebooks. For new content, use the CREDENTIAL_VAULT_ENTRY- ID.

Update the JavaScript code

Run JavaScript tasks, JavaScript code in dashboards and notebooks, and app functions that read or manage credentials must switch from credentialVaultClient to credentialVaultEntriesClient in the @dynatrace-sdk/client-credential-vault package.

Before:

import { credentialVaultClient } from '@dynatrace-sdk/client-classic-environment-v2';
const { token } = await credentialVaultClient.getCredentialsDetails({ id: 'CREDENTIALS_VAULT-XXXXXXXXXXXXXXXX' });

After:

import { credentialVaultEntriesClient } from '@dynatrace-sdk/client-credential-vault';
const { token } = await credentialVaultEntriesClient.getCredentialVaultEntryDetails({ entryId: 'CREDENTIAL_VAULT_ENTRY-XXXXXXXXXXXXXXXX' });

The client name and method names have changed, and the id parameter is now entryId:

OperationClassic SDKNew SDK
ListlistCredentials()listCredentialVaultEntries()
CreatecreateCredentials()createCredentialVaultEntry()
GetgetCredentials()getCredentialVaultEntry()
Get detailsgetCredentialsDetails()getCredentialVaultEntryDetails()
List detailsgetCredentialsDetailsList()listCredentialVaultEntryDetails()
UpdateupdateCredentials()updateCredentialVaultEntry()
DeleteremoveCredentials()deleteCredentialVaultEntry()

getCredentialVaultEntry() returns entry metadata only. To retrieve the secret value, use getCredentialVaultEntryDetails().

Update permissions

Who needs the new permissions depends on where the code runs.

Workflows

Every workflow runs under an actor, the user or service user whose permissions determine what the workflow can access. The actor needs permissions in two places:

  • IAM policies: the actor's own permissions. This applies to every actor, including service users.
  • Workflows authorization settings: only if the actor isn't a service user. A service user runs the workflow directly with its own permissions. A user runs the workflow through Workflows Workflows, which can only use the permissions the user has authorized. To change them, the user goes to Workflows Workflows > Settings > Authorization settings and turns on the permission under Secondary permissions. Only that user can change their own authorization settings.

If a permission is missing, tasks that read credentials fail with a 403 error.

Before you start

  1. Identify workflows that use credential vault entries: Run JavaScript tasks that call the credential vault SDK, and HTTP request tasks that use a stored credential for authentication.
  2. Find the actor of each workflow. In the workflow editor, select next to Run and Executions, and check the details pane. For HTTP request tasks, you can also use the query below.

Update permissions for workflows with Run JavaScript tasks

The new SDK already works before you move to the Latest Dynatrace, so you can switch and test at any time.

  1. Make sure the actor has credential-vault:entries:read through an IAM policy. If the code creates, updates, or deletes entries, the actor also needs credential-vault:entries:write.
  2. If the actor isn't a service user, the actor must turn on credential-vault:entries:read in their own authorization settings. An administrator can't do this for them.
  3. Make sure the credential entries still allow access.
  4. Update the JavaScript code to use the new SDK package.
  5. Run the workflow and confirm that the tasks complete successfully.

Update permissions for workflows with HTTP request tasks

You don't need to change the task. Until you move to the Latest Dynatrace, the actor needs both the Classic and the new permissions. Don't remove the Classic permissions before the move.

  1. Find the actors of HTTP request tasks that use credentials. To list the users and service users that run workflows with HTTP request tasks that read credentials, run the following query in Notebooks Notebooks. It returns one row per actor, with the last call, the number of calls, the number of denied calls (403), and the IDs of the workflows.

    fetch dt.system.events, from:-30d
    | filter event.kind == "AUDIT_EVENT" and event.provider == "API_GATEWAY"
    | filter dt.app.id == "dynatrace.automations" and dt.app.function == "api/http-function"
    | filter startsWith(resource, "/platform/classic/environment-api/v2/credentials")
          or startsWith(resource, "/platform/credential-vault/")
    | summarize
      {
        last_used   = max(timestamp),
        calls       = count(),
        denied      = countIf(event.outcome == "403"),
        workflows   = collectDistinct(details.dt.automation_engine.workflow.id)
        },
        by: { user.id }
    | lookup [
        fetch dt.system.events, from:-30d
        | filter event.kind == "BILLING_USAGE_EVENT" and isNotNull(user.email)
        | summarize n = count(), by: { user.id, user.email }
      ], sourceField: user.id, lookupField: user.id, fields: { user.email }
    | fieldsAdd service_user = if(isNull(user.email), "unknown",
                               else: if(endsWith(user.email, "@service.sso.dynatrace.com"), "yes", else: "no"))
    | fields user.id, user.email, service_user, last_used, calls, denied, workflows
    | sort last_used desc

    The service_user column shows whether the actor is a service user. It shows unknown if the query can't resolve the user ID to an email address. If some workflows run less often than every 30 days, increase the from: timeframe.

  2. Make sure the actor has environment:roles:viewer and credential-vault:entries:read through IAM policies.

  3. If the actor isn't a service user, the actor must turn on both environment-api:credentials:read and credential-vault:entries:read in their own authorization settings. An administrator can't do this for them.

  4. Make sure the credential entries still allow access.

Use a service user as actor

This step is optional. We recommend using service users as actors for workflows that several people work on and that serve a production use case. A service user as actor has two advantages:

  • The actor doesn't change when someone edits the workflow.
  • The workflow doesn't depend on one user's authorization settings.

To assign a service user as actor, you need the iam:service-users:use permission.

Update permissions for dashboards and notebooks

JavaScript code in dashboards and notebooks runs with the permissions of the user who runs it. Authorization settings and service users don't apply.

  1. Identify dashboards and notebooks that call the credential vault SDK in JavaScript code.
  2. Make sure every user who runs this code has credential-vault:entries:read through an IAM policy. If the code creates, updates, or deletes entries, the user also needs credential-vault:entries:write.
  3. Make sure the credential entries still allow access.
  4. Update the JavaScript code to use the new SDK package.
  5. Run the code and confirm that it completes successfully.

If a permission is missing, the code fails with a 403 error.

Credential entry settings

You don't need to change your credential entries for the upgrade. As a reminder, workflows, dashboards, and notebooks can only use a credential if its AppEngine scope and access settings allow it:

  • HTTP request tasks: under Dynatrace apps with access, All applications or Workflows Workflows is selected.
  • Run JavaScript tasks, and JavaScript code in dashboards and notebooks: Allow access without app context is turned on.
  • The workflow actor or the user who runs the code owns the credential or is listed in Users with access. To list a service user, enter its email address, which you can find under Service users.

Verify

After you update the code and permissions, run the workflow or the code and confirm that it completes successfully. For Run JavaScript tasks, dashboards, and notebooks, you can do this before you move to the Latest Dynatrace. For HTTP request tasks, do it after you move to the Latest Dynatrace, or wait for the next scheduled execution.

Then remove environment:roles:viewer from the actor or user, unless they need it for other purposes. If the actor isn't a service user, they can also turn off environment-api:credentials:read in their authorization settings.

Troubleshooting

If code or a task that uses a credential fails, for example with a 403 error, check the following:

  • The actor or user has credential-vault:entries:read through an IAM policy (HTTP request tasks before you move to the Latest Dynatrace: also environment:roles:viewer). See Update permissions. Custom policies and policy boundaries can remove a permission that a default policy grants.
  • Workflows only: if the actor isn't a service user, credential-vault:entries:read is turned on under Secondary permissions in the authorization settings (HTTP request tasks before you move to the Latest Dynatrace: also environment-api:credentials:read).
  • The credential is configured for access, and the actor or user owns it or is listed in Users with access. See Credential entry settings.
  • Workflows only: the actor hasn't changed, for example because someone else edited the workflow. If it has, reassign the intended actor or use a service user.

Related topics

  • Credential vault
  • Manage workflow permissions
  • Upgrade from Classic access tokens to platform tokens
  • Working with policies
Related tags
Dynatrace Platform