Migrate from Tokens v1 API to Access tokens API

Tokens API v1 has been deprecated with Dynatrace version 1.242. Its replacement is Access tokens API. We recommend that you migrate to the new API at your earliest convenience.

The migration affects endpoint URLs, query parameters, and response/request body parameters, as well as the scope of the token for request authentication.

New features

The Access tokens API offers you the following new features:

  • Possibility to create personal access tokens.
  • Improved overview of token usage with the last used IP address, which can help in identifying a leaked token.
  • Additional metadata for specific token types.

Base URL

new Access tokens
old Tokens v1
/api/v2/apiTokens
/api/v1/tokens

Authentication token scope

new Access tokens
old Tokens v1
Read API tokens (apiTokens.read)
Write API tokens (apiTokens.write)
Token management (TenantTokenManagement)

Parameters

To learn about new query/body parameters, see the documentation of individual requests in Access tokens API.

Examples

Here are some examples of differences in API usage.

Create a new token

In this example, we create a token with the Read metrics (metrics.read) scope and a validity period of 30 days.

Request URL

POST https://mySampleEnv.live.dynatrace.com/api/v2/apiTokens

Request body

{
  "name": "tokenName",
  "expirationDate": "now+30d",
  "scopes": [
    "metrics.read"
  ]
}

Query a list of tokens

In this example, we query all tokens that have been used since July 1, 2022.

In the Access tokens API, you can control which fields are returned with the list query (via the fields parameter). In this example, we use name, owner, and lastUsedDate fields.

The timeframe is defined via the from query parameter. It supports multiple formats; see the individual request documentation to learn more about them.

The result of the query is split into pages. You can control the page size with the pageSize parameter. In this example, the parameter is not set; therefore, the default of 200 entries per page is used.

Request URL

GET https://mySampleEnv.live.dynatrace.com/api/v2/apiTokens?from=2022-07-01T00:00:00&fields=name,owner,lastUsedDate

Query parameters

from=2022-07-01T00:00:00
fields=name,owner,lastUsedDate

Response body

{
  "totalCount": 3,
  "pageSize": 200,
  "apiTokens": [
    {
      "id": "dt0c01.HHG2Y66QSCRZM4N3MPSCNNG2",
      "name": "John's token",
      "owner": "john.smith@company.com",
      "lastUsedDate": "2022-07-26T13:21:00.147Z"
    },
    {
      "id": "dt0c01.2KVOGE5JTIHSAMWU5HRKO4SD",
      "name": "Jane's token",
      "owner": "jane.brown@company.com",
      "lastUsedDate": "2022-07-26T11:20:12.825Z"
    },
    {
      "id": "dt0c01.ZCSMXFBRSTWPEUEUOL2HJ45K",
      "name": "James' token",
      "owner": "james.williams@company.com",
      "lastUsedDate": "2022-07-26T10:03:04.964Z"
    }
    ]
}

Related topics