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 Central Management, Delphix offers a password-less option for interacting with Engine APIs. 

Central Management provides the means to generate API keys which can be used by scripts or other processes to access APIs on Masking or Virtualization Engines.

Generating API Keys

To generate an API key:

1. Login to Central Management.
2. Navigate to the API Keys tab. 
3. Click Create New Key.
   
   
4. In the subsequent modal, provide the following:
   
   
1. In the API Key Name provide the name of the API Key.
2. In the Description (optional) text field, provide a description.
3. 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.
5. Click Next.

6. 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.
7. Click Finish to complete the process. You will be able to view the details on the API list. 

Using an API Key

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:

1. Generate An Access Token
2. Establish A Session 
3. 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. 

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://delphix.okta.com/oauth2/default/v1/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 endpoints 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'

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.

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 below steps: 

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