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.

Access tokensTokens v1

Request URL

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

Request body

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

Request URL

plaintext
POST https://mySampleEnv.live.dynatrace.com/api/v1/tokens

Request body

json
{
  "name": "tokenName",
  "expiresIn": {
    "value": 30,
    "unit": "DAYS"
  },
  "scopes": [
    "metrics.read"
  ]
}

Query a list of tokens

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

Access tokensTokens v1

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

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

Query parameters

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

Response body

json
{
  "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"
    }
    ]
}

In Tokens API v1, you can't control which fields are returned—these are always id and name.

The timeframe is defined via the from query parameter. Its format is a timestamp in UTC milliseconds.

All the tokens are returned in a single payload; pagination is not available.

Request URL

plaintext
GET https://mySampleEnv.live.dynatrace.com/api/v1/tokens?from=1656626400000

Query parameters

plaintext
from=1656626400000

Response body

json
{
  "values": [
    {
      "id": "fb015532-0078-4ce1-8eb6-abe17e58bb4c",
      "name": "John's token"
    },
    {
      "id": "4197e25b-3090-4bbc-8140-ddc1621565eb",
      "name": "Jane's token"
    },
    {
      "id": "65e2af47-9b35-4734-ad0d-b47a233c12c4",
      "name": "James' token"
    }
    ]
}