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
Authentication token scope
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"
]
}
Request URL
POST https://mySampleEnv.live.dynatrace.com/api/v1/tokens
Request body
{
"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.
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"
}
]
}
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
GET https://mySampleEnv.live.dynatrace.com/api/v1/tokens?from=1656626400000
Query parameters
Response body
{
"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"
}
]
}