Documentation forDatabase Performance Analyzer

Manage tokens used for authentication to the DPA API

About refresh tokens and access tokens

Token-based authentication allows users to access the API without entering credentials to authenticate every request. Two types of tokens are required to authenticate requests to the DPA API:

  • An access token is a secure string required to authenticate requests to access the API.

    By default, an access token expires after 900 seconds. (You can change the default lifespan by editing the advanced option API_ACCESS_TOKEN_EXPIRATION.) Access tokens have short lifespans for security reasons. The short lifespan makes it less likely for the access token to be accessed by a malicious actor.

    Access tokens also expire if the DPA server is rebooted, or if the issuing refresh token expires or is deleted.

  • A refresh token is used to issue access tokens. Refresh tokens typically have long lifespans. They are generated in DPA and stored in a secure location. Before a script or application calls the API, it uses a refresh token to obtain an access token. If the access token expires before the activity is complete, the refresh token can automatically request a new access token.

To obtain the tokens that are required to make calls to the API:

  1. An administrator creates a refresh token through the DPA interface and stores it in a secure location.

    When you create a refresh token, you can specify the expiration date or set it to never expire. The default expiration date is 90 days from the creation date. You can change the default by editing the advanced option API_REFRESH_TOKEN_EXPIRATION.

  2. Before a script or application makes calls to the API, it uses the refresh token to obtain an access token. The script or code can also include a function to verify that the access token is still valid and acquire a new access token if necessary.

    The Python and PowerShell script examples show how to use the refresh token to obtain an access token.

Create a refresh token

  1. Log in to DPA as a user with administrative privileges.
  2. From the DPA menu in the upper-right corner, click Options.
  3. Under Users & Contacts, click Refresh Token Management.
  4. On the API Refresh Token Management page, click Create token.

  5. Enter a name and specify when the token expires.

    By default, refresh tokens for the DPA API expire after 90 days. However, you can choose to create refresh tokens that never expire.

  6. Click Create. The token string is displayed.

  7. Click Copy to clipboard, and then click Close.

If you create a refresh token and fail to copy the string or lose the copied string, the refresh token cannot be used. Delete that token and create a new one.

About storing refresh tokens

Store refresh tokens in a secure location, such as a password-protected file system or an encrypted database. Limit access to users who need the tokens to make API calls.

If you believe that a refresh token has been accessed by an unauthorized user, delete it and create a new one.

Delete a refresh token

You can delete a refresh token at any time. For example, you can delete refresh tokens that have expired. If you delete a refresh token that has not expired, any access tokens obtained using that refresh token are invalidated and can no longer be used.

  1. Log in to DPA as a user with administrative privileges.
  2. From the DPA menu in the upper-right corner, click Options.
  3. Under Users & Contacts, click Refresh Token Management.
  4. On the API Refresh Token Management page, select one or more tokens.

  5. Click Delete.