Programmatic access to DCS (API Tokens)

Overview

In Salesforce, triggering compliance jobs just after sandboxes have refreshed is a common pattern. This reduces the time that a sandbox has production data in it. To achieve this, Salesforce teams like to automate the entire sandbox refresh process as follows: 

1. Trigger refresh

2. Trigger post-refresh to drop users

3. Delphix compliance (data masking)

4. Script to recreate non-prod users

API tokens are being introduced in DCS as a means to address this situation. These API tokens are JWTs (JSON Web Tokens) that can be generated for a customisable lifespan.

Once the token is created, it can be utilized to carry out tasks such as creating connectors, managing rulesets, algorithms, executing compliance jobs, and more.

Creating a new token

1. Login to DCS and select the Accounts tab at the top, then navigate to the API Tokens page by selecting API Tokens.

2. Select the Add Token button in the top right corner, above the table. This will initiate the window shown below, with the following options:

   1. Associated user: The email address of the currently logged-in user.

   2. Description: An optional field allowing users to assign a name to the token being created. It's important to note that this name must be unique among all tokens in the tenant, otherwise, an error message will be displayed. If left blank, the system will automatically generate a unique name for the token.

   3. Lifespan (days): An optional field indicating the number of days after which the token will expire. The minimum lifespan for a token is one (1) day. To create a token with no expiration, simply leave this field empty.

3. Click on Generate Token to generate a new API token with the provided information as shown below. The generated token will be available to copy on the clipboard as long as the window is open.

Once the window is closed, there will be no option to view the token. 

4. Once a token is generated, the Delete Token button will become enabled, which can be used to delete the token if needed.

5. Once complete, close the window by clicking Close or the X button in the window header. The token created will be displayed in the table.

If the description or the lifespan of the token needs to be changed, delete the token, modify the description/lifespan, then generate the token again.

Viewing existing tokens

On the main page, all API tokens belonging to the logged-in user’s tenant can be found. Each entry in the list includes the following information.

• API Token Description: The API token name serves as a unique identifier, either set to the input token name provided during creation or generated by the system. This field helps identify each API token within the list. To match an API token created with an auto-generated name to its list entry, compare the first four and last four characters of the token with the entries under API Token Description.

  • For example, if the token begins with eyJH and ends with hgft, the corresponding API Token Description field would have the same prefix and suffix, with randomised characters in between, such as eyJH..XbLOiHLNDTM..hgft.

• Token Status: Indicates the present status of the token. For an active one, the token status displays the date and time of when the token is set to expire in the future: Enabled - Expires on MM DD, YYYY HH:MM. If a token has already expired, the status is shown as Expired.

• Associated user: Displays the email address of the user who created the token.

Deleting a token

To revoke access to an API token, utilize the UI to delete it. If any API request is executed with a deleted token, the caller will encounter an unauthorized exception. This holds true regardless of the token's expiration. For instance, if a token is set to expire in 30 days but gets deleted any time before that, it is promptly removed from the system. Follow these steps to delete an existing API token.

1. Click on the ellipsis icon within the table corresponding to the API Token, then select Delete Token, which will open the delete token window.

2. Enter the token description in the input text field as confirmation for deletion.

3. Click Delete Token to do as described and close the window.

It is important to note that once a token is deleted, it cannot be recovered.

Making API requests using API Tokens 

The users must send their API token as a Bearer token in the Authorization header when making API requests to DCS: