Authentication with the Database Performance Monitor API is done via API tokens. Tokens should be treated like passwords, as they allow access to the data in your account. When contacting Support, do not include the API token in any emails or chat messages.

To create an API token, log in to your DPM account and select an Environment (API tokens are linked to an environment, which dictates what data to collect). Navigate to Settings and then select API Tokens.

Tokens are created with a specific Role, which defines the actions a user will be allowed to take when using the token. For more information on the meaning of each Role, see our RBAC Documentation. In general, if you are fetching data from the API, use the Read Only or Read-Only (with samples) roles.

When making API requests, include the API token in each call using the Authorization:Bearer header. For example, here’s a sample curl request which will fetch hosts that were active in the past hour.

curl 'https://app.vividcortex.com/api/v2/hosts?from=-3600&nest=tags&until=0' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Accept: application/json, */*' \
-H 'X-Indent: true'

Throughout the API documentation, <API_TOKEN> is used as a placeholder.

Rotating Tokens

If you believe that an API or agent token has been compromised, you can use the API tokens page to generate a new token and deprecate the old token. Both API tokens and agent tokens can be rotated through this page; if you need a new token for an SSO integration, create a new token through the Authentication page.

Rotating a token involves three steps: creating a new token, replacing the old token with the new token wherever it is used, and removing the old token. Special steps are required when rotating an agent token (see below).

Step 1: Create a New Token

To begin the process of replacing an old token with a new token, click the “Rotate” button next to the token you would like to replace. Once started, this cannot be undone. When you click Rotate, you will be given a new token; be sure to copy it, as it will only be displayed once. When rotating an API token, this new token will have the same configuration and permissions as the token it is replacing. Replacing an agent token requires an extra step (see Step 2). After clicking Rotate and copying the token, the page will look like this:

If while replacing the old token this new token is compromised, you can rotate the token again by clicking “Rotate”. This will create a new token that you can copy and use.

Step 2: Replace the Old Token

With the new token provided after clicking Rotate, replace the old token in each place it is used. For API tokens, this might include custom scripts your team has created or our Grafana integration.

Agent tokens are used by each agent for communication with our API. As with the tokens displayed during the on-host or off-host installation process, this token has limited permissions and must be exchanged for for a permanent token. You can get the new, permanent agent token in one of two ways:

• Use this temporary token to make the following API request: curl 'https://app.vividcortex.com/api/v2/installtokens' -H 'Accept: application/json' -H "Authorization: Bearer $ROTATION_TOKEN"
• Open Add New Host on the Inventory page, and select “Containerized.” The updated agent token will be displayed. In this case you do not need the token displayed during rotation for anything.

Step 3: Finish rotation

The “Last Used” column indicates the last time a token was used in an API call (“Unknown” indicates that it has never been used.) Once you have confirmed that the deprecated token (or tokens) is no longer in use, click “Finalize.” This will permanently deactivate all of the deprecated tokens. If you wish to deactivate one of the tokens created as part of this process but not yet Finalize the entire rotation, click the trash can icon next to the individual token of your choice.