Implement token rotation

Regularly changing your password is a good security practice. Same goes for Dynatrace API authentication tokens.

With the Tokens API, you can automate the rotation.

Get the ID of an old token

Create a new token

Revoke the old token
Don't delete it before you revoke it.

Delete the old token

For a workflow example, let's assume you want to rotate a token with following parameters:

Get the ID of an old token

If you only know the token itself, you need to obtain its ID to revoke and subsequently delete it. To do so, issue a POST token lookup request with the token to be deleted as the payload.

The request returns the metadata of the token, including its ID, which you will need later.

Request

Send a POST request to this URL:

Include this application/json payload, where 0987654321jihgfedcba is the token value:

{
  "token": "0987654321jihgfedcba"
}

Response

The request returns the metadata of the token in the application/json payload:

{
  "id": "a6e91657-1fa7-4742-af40-39469b92bd65",
  "name": "RW config token",
  "userId": "admin@mysampleenv.com",
  "created": "2019-03-06T09:15:49Z",
  "expires": "2019-04-05T09:15:49Z",
  "scopes": [
    "ReadConfig",
    "WriteConfig"
  ]
}

You need to retrieve token's id value, which you will need to retire (revoke and delete) this token.

Create a new token

To create a new token that will replace the outdated one, execute a POST a new token request. Since you create a token with same parameters on a regular basis, you might consider storing its configuration in a version control system.

Request

Send a POST request to this URL:

Include this application/json payload:

{
  "name": "RW config token",
  "scopes": [
    "WriteConfig",
    "ReadConfig"
  ],
  "expiresIn": {
    "value": 30,
    "unit": "DAYS"
  }
}

Response

The request returns the new token in the application/json payload:

{
  "token": "jihgfedcba0987654321"
}

Revoke the old token

To revoke the old token, execute PUT an existing token. You will need the token id value you obtained in step 1.

A revoked token cannot be used for authentication, but it still exists in your environment. We recommend that you wait a week before deleting a revoked token, in case there is an emergency need for it. Check your organization's security policies for the exact delay.

In our example, the ID of the token to be revoked is a6e91657-1fa7-4742-af40-39469b92bd65.

Request

Send a PUT request to this URL:

Include this application/json payload:

{
  "revoked": true
}

Response

A successful request is indicated by the 204 response code. It doesn't return any content.

Delete the old token

After the waiting period, with the old token disabled (revoked), delete it. To do so, execute DELETE an existing token. You will need the ID of the token you obtained in step 1.

In our example, the ID of the token to be deleted is a6e91657-1fa7-4742-af40-39469b92bd65.

Request

Send the DELETE request to this URL:

Response

A successful request is indicated by the 204 response code. It doesn't return any content.