Documentation forDatabase Performance Analyzer

Manage tokens used for authentication to the DPA API

Two types of tokens are required to authenticate requests to the DPA API:

  • An access token is a session (stateless) that is required to make authenticated calls to the DPA API. Access tokens are obtained using a refresh token when needed (for example, at the beginning of a script that makes API calls, or when you use the Swagger interface to experiment with the DPA API).

    By default, an access token (session) expires after 900 seconds. You can change the default by editing the advanced option API_ACCESS_TOKEN_EXPIRATION. Access tokens also expire if the DPA server is rebooted, or if the issuing refresh token expires or is deleted. Access tokens have short lifespans for security reasons.

    For activities that require more than 900 seconds, scripts can include a function to verify that the access token is valid and acquire a new access token if necessary.

  • A refresh token is used to obtain access tokens. Refresh tokens are obtained through the DPA interface by an administrator and stored in a secure location, as described below.

    Refresh tokens typically have long lifespans. When you create a refresh token, you can specify the expiration date or set it to never expire. The default expiration date is after 90 days. You can change the default by editing the advanced option API_REFRESH_TOKEN_EXPIRATION.

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.