Delphix strongly discourages using password-based authentication (traditional usernames and passwords) for API authentication. Much like how a SAML2-compliant SSO vendor can be used for users to authenticate to Data Control Tower, Delphix offers a password-less option for interacting with Engine APIs.

Data Control Tower provides the means to generate API keys which can be used by scripts or other processes to access APIs on Masking or Virtualization Engines and Data Control Tower public APIs.

Generating API Keys

To generate an API key:

Login to Data Control Tower as an Admin User.
Navigate to the API Keys tab.
Click Create New Key.
In the subsequent modal, provide the following:

In the API Key Name provide the name of the API Key.
In the Description (optional) text field, provide a description.
In the Associated Email Address text field, provide an email address in which the API key will execute any required tasks. This must associate with a user email address that exists on the engines against which the API key will be used. Admin Users may choose any email address. Standard users can only use their own email address.

Click Next.
On Get Key page, you can either copy the Client ID and Client Secret credentials using the icon to copy or download the credential using the Download CSV button.

You will not be able to retrieve the Client Secret after this point.
Click Finish to complete the process. You will be able to view the details on the API list.

Delphix Engine APIs

The API key is meant to replace the username and password previously used to authenticate API calls. The approach, however, will remain the same. Specifically, to execute a call against a Virtualization or Masking Engine, you must:

Generate An Access Token
Establish A Session
Execute Commands

Where this flow differs from normal is in step 2 "Establishing a Session", where the Client ID and Client Secret are used in place of username and password.

API calls will be executed on behalf of the user account whose email address was associated when the API key was create

Generating an Access Token

The following example uses curl to establish a session, but you may use whatever mechanism you choose to test.

curl -XPOST https://api.delphix.com/oauth2/token \
   -H 'accept: application/json' \
   -H 'content-type: application/x-www-form-urlencoded' \
   -d 'grant_type=client_credentials&scope=groups' --user $client_id:$client_secret

Replace $client_id and $client_secret with the values you generated in the Generating API Keys section.

Upon a success to API call, you will receive a response that looks like below (note that the response in “access_token” has been shortened for readability)

{"token_type":"Bearer","expires_in":3600,"access_token":"eyJra… xqbT-EScTI-g","scope":"groups"}

The value in access_token (within the quotations) is required for the next step. This access token will be valid for a one-hour duration from the time it was generated.

Establishing a Session

Replace delphix-server with the IP address or a fully qualified domain name of your Delphix Engine.

Delphix suggests you use the API latest version. Check the latest Virtualization and Masking API versioning. In the following examples, replace $access_token with the long string generated at the Generate An Access Token.

Example for Virtualization

curl -XPOST http://delphix-server/sso/virtualization/api/login -H "Authorization: Bearer $access_token" -c ~/cookies.txt -H "Content-Type: application/json" -d '{"type": "APISession", "version": {"type": "APIVersion","major": 1,"minor": 10,"micro": 5}}'

A successful result is shown below:

{"type":"OKResult","status":"OK","result":{"type":"APISession","version":{"type":"APIVersion","major":1,"minor":10,"micro":5},"locale":null,"client":null},"job":null,"action":null}

Example for Masking

curl -XPOST http://delphix-server/masking/api/v5.0.0/sso-login -H "Authorization: Bearer $access_token"

A successful result is shown below:

{"Authorization":"14defd2a-2c...2-df663ec55345"}

Executing Commands

This section provides a few examples when you query the e ndpoints of the Delphix Engine in Virtualization and Masking area:

Example for Virtualization

When you query the about endpoint of the Delphix Engine. This command below will provide the basic information about the Delphix Engine.

curl -X GET -k http://delphix-server/resources/json/delphix/about \
    -b ~/cookies.txt -H "Content-Type: application/json"

Example for Masking

When you query the system-information endpoint of the Delphix Engine. This command below provides the basic system information.

curl -X GET --header 'Accept: application/json' --header '$authorization_key' 'http://18.207.235.194/masking/api/system-information'

Disabling Username and Password API Authentication

We know that transitioning all of your scripts and automation to using API keys may not happen all at once. Username and password API-based authentication for each engine user will continue to be active until you explicitly disable it.

To disable the Username and Password API authentication, perform the below steps:

Login to the Delphix Management application.
Navigate to each of your Delphix Virtualization and Masking engines.
Click Manage > Users.
Navigate to the Users page.
Edit the user for disabling the user name and password API authentication.
Uncheck the Enabled box in the API access via username and password section.
Click Submit to save authentication settings.

Data Control Tower APIs

For Data Control Tower APIs the API keys are used to generate an access token using standard OAuth2 client credentials flow. The access token is used to make authenticated API calls on DCT.

Generating an Access Token

The following example uses curl to generate an access token, but you may use whatever mechanism you choose to test.

curl -XPOST https://api.delphix.com/oauth2/token \
   -H 'accept: application/json' \
   -H 'content-type: application/x-www-form-urlencoded' \
   -d 'grant_type=client_credentials&scope=groups' --user $client_id:$client_secret

Replace $client_id and $client_secret with the values you generated in the Generating API Keys section.

Upon a success to API call, you will receive a response that looks like below (note that the response in “access_token” has been shortened for readability)

{"token_type":"Bearer","expires_in":3600,"access_token":"eyJra… xqbT-EScTI-g","scope":"groups"}

The value in access_token (within the quotations) is required to make API calls. This access token will be valid for a one-hour duration from the time it was generated.

Execute Data Control Tower API using Access Token

The following example assumes the access token value has been assigned to $access_token environment variable. Example calling /engines for a list of DCT registered engines:

curl -X 'GET' \
  'https://api.delphix.com/v1/engines' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $access_token"

Existing Data Controler Tower APIs

All current APIs are GET operations similar to the example /engines end-point.

/engines
/engines/{engineId}
/sources
/sources/{sourceId}
/dsources
/dsource/{dsourceId}
/vdbs
/vdbs/{vdbId}

Rotating API Keys

Key rotation for accessing Delphix APIs is possible to perform without causing service interruptions for any scripts or processes using them. For each API Key, two sets of client secret pairs can be created so that a second one is deployed and used before the first one is disabled.

DCT API Client SDK Generation

The DCT (SaaS) API specification is published and can be found here: https://api.delphix.com/v1/api-docs/

Generating Client SDKs

Client DCT API SDKs for most languages can be generated using the OpenAPI Generator. There are multiple ways to install and use the OpenAPI Generator CLI tool. Instructions for installation and usage can be found here.

To generate an SDK, the OpenAPI Generator tool requires an OpenAPI specification document. The API specification can either be downloaded before running the tool or downloaded by the tool itself.

Using OpenAPI Generator Docker Image

The following sections will use the OpenAPI Generator Docker image to generate a client SDK for Golang. The same steps can be followed for other languages (e.g. Java, Python, C#, etc.).

Download DCT API Specification

To generate an SDK, the OpenAPI Generator tool requires the API specification. The API specification can be downloaded using cURL:

curl -o dct.yaml https://api.delphix.com/v1/api.yaml

Generate Golang SDK

Generate SDK using the Docker image and the downloaded API specification file:

docker run --rm \
    -v $PWD:/local openapitools/openapi-generator-cli generate \
    -i /local/dct.yaml \
    -g go \
    -o /local/out/go

Generate SDK using the Docker image and API specification URL:

docker run --rm \
    -v $PWD:/local openapitools/openapi-generator-cli generate \
    -i https://api.delphix.com/v1/api.yaml \
    -g go \
    -o /local/out/go

Generated output for Golang:

out/go
├── README.md
├── api
│   └── openapi.yaml
├── api_bookmarks.go
├── api_d_sources.go
├── api_engines.go
├── api_environments.go
├── api_sources.go
├── api_vd_bs.go
├── client.go
├── configuration.go
├── docs
│   ├── Bookmark.md
│   ├── …
│   └── Vdb.md
├── git_push.sh
├── model_bookmark.go
├── model_create_bookmark_response.go
├── model_d_source.go
├── model_engine.go
├── model_environment.go
├── model_error.go
├── model_host.go
├── model_list_bookmarks_response.go
├── model_list_d_sources_response.go
├── model_list_engines_response.go
├── model_list_environments_response.go
├── model_list_sources_response.go
├── model_list_vd_bs_response.go
├── model_source.go
├── model_vdb.go
└── response.go

Data Control Tower (SaaS)

Using DCT and Delphix Engine APIs

Generating API Keys

Delphix Engine APIs

Generating an Access Token

Establishing a Session

Example for Virtualization

Example for Masking

Executing Commands

Example for Virtualization

Example for Masking

Disabling Username and Password API Authentication

Data Control Tower APIs

Generating an Access Token

Execute Data Control Tower API using Access Token

Existing Data Controler Tower APIs

Rotating API Keys

DCT API Client SDK Generation

Generating Client SDKs

Using OpenAPI Generator Docker Image

Download DCT API Specification

Generate Golang SDK