Skip to main content
Skip table of contents

API Key Authentication

LAST UPDATED: MARCH 28, 2025

An API key is a unique token used to authenticate systems or applications accessing a platform via an application programming interface (API). This article outlines the steps for sending an API key-authenticated request using Postman to interact with the D3 platform.

Prerequisites

  • Postman

  • Ability to set up D3 webhook keys

Setting Up API Keys for Data Ingestion

  1. Establish a connection between D3 vSOC and the integration. This connection must be active and display a status, as shown in the image below.

    Frame 6 (1).png

    Ensure the connection is associated with a specific site. The connection in the screenshot is linked to the Security Operations site.

  2. Select the event/incident intake command, such as Fetch Event.

    Group 7.png

  3. Ensure that Webhook Authentication is toggled on.

  • On: image 1 (2)-20241205-203600.png

  • Off: image 3 (4)-20241205-203551.png

From this point, users can configure their API key through either the Integrations module or the Data Ingestion module.

Setting Up API Keys from the Integrations Module

  1. Click on the API Key button.

    Group 9 (1).png

  2. Set up the API key within the Setup API Key popup.

    Group 10.png

    1. Click the + button in the INTERNAL SITES or CLIENT SITES section.

    2. Select the Site to be used for the data ingestion job.

    3. Enter a unique Key Name.

    4. Click the Generate button.

The user will see a display similar to the following:

Group 17.png

READER NOTE

If users click the + button in the ALL SITES section, then select Shared to All Internal Sites or Shared to All Client Sites for the Site field, the API key will be shared with all corresponding sites. However, users must still select a specific site for data ingestion.

Group 22 (1).png

Users can add an API key to share with all internal or client sites by clicking the + button in the ALL SITES section.

Group 42.png

The Site field can be set to either Shared to All Internal Sites or Shared to All Client Sites.

Group 20 (1).png

The internal_key API key is shared with all internal sites, but users must still select a specific internal site for data ingestion.

Group 21.png

The client_key API key is shared with all client sites, but users must still select a specific client site for data ingestion.

Setting Up API Keys from the Data Ingestion Module

  1. Navigate to the Configuration module, then click the Data Ingestion sub-module.

    Group 12.png

  2. Click the + button, then select the Webhook option.

    Group 13.png

  3. Configure the webhook data source.

    Group 14.png

    1. Select the integration to use, such as Wiz.

    2. Choose the site into which the data will be ingested.

    3. Select the API Key checkbox in the Authentication Method section.

    4. Click the + button to add a new API key.

  4. Enter a unique Key Name, then click the Generate button.

    Group 15.png

The user will see a display similar to the following:

Group 16.png
Setting Up API Keys for Integration Commands

  1. Establish a connection between D3 vSOC and the integration. This connection must be active and display a status, as shown in the image below.

    Frame 12.png

    Ensure the connection is associated with a specific site. The connection in the screenshot is linked to the Security Operations site.

  2. Select the desired integration command.

    Frame 13.png

    For demonstration purposes, the Get Computers command will be used.

  3. Ensure that Webhook Authentication is toggled on, then click the the API Key button.

    Frame 8.png

  • On: image 1 (2)-20241205-203600.png

  • Off: image 3 (4)-20241205-203551.png

  1. Set up the API key within the Generate Remote Command Key popup.

    Group 5 (1).png

    1. Click the + button within the Setup API Key popup.

    2. Select the connection created from step 1. The connection should have the name of the site it is linked to in parentheses.

    3. Enter a unique Key Name.

    4. Click the Generate button.

The user will see a display similar to the following:

Group 6.png

Users must select a site to display and copy the API request URL.

select a site.gif

READER NOTE

If users selected a connection that was shared with all internal sites, then they will not see the Select Site dropdown.

Group 43 (1).png
Setting Up API Keys for Utility Commands

  1. Ensure that Webhook Authentication is toggled on, then click the API Key button.

    Frame 4.png

  • On: image 1 (2)-20241205-203600.png

  • Off: image 3 (4)-20241205-203551.png

  1. Set up the API Key in the Generate Remote Command Key pop-up.

    Group 1.png

    1. Click the + button within the Setup API Key popup.

    2. Enter a unique Key Name.

    3. Click the Generate button.

The user will see a display similar to the following:

Group 3 (1).png

Sending an API Key-Authenticated Request: Data Ingestion

Users can send an API key-authenticated request to push data into D3 using the webhook data ingestion method to create D3 events.

READER NOTE

For clarity, the example below demonstrates how to send an API key-authenticated request using Postman. However, this approach is intended only for testing purposes. In typical use cases, webhook ingestion is handled automatically through external software or scripts.

  1. Copy the request URL in vSOC.

    Group 31.png

  2. In Postman, set the HTTP request method to POST, then paste the request URL in the designated field.

    Group 32.png

  3. In vSOC, copy the request header key.

    Group 25.png

  4. In Postman, click on the Headers tab, then paste the request header key under the Key column.

    Group 26.png

  5. In vSOC, copy the request header value.

    Group 33.png

  6. In Postman, paste the request header value under the Value column.

    Group 28.png

  7. Select the Body tab, choose the raw option, then paste sample request body data.

    Group 35.png

READER NOTE*

The request body data is copied from the raw sample available under the Outputs > Raw Data tab of Wiz’s Fetch Event command. Any D3 events created using this data are not real security events.

Group 36.png

Users can treat this as a template for structuring data pushed into D3 to create D3 events, specifically for Wiz’s Fetch Event command. For example, this demonstrates that the main event JSON path is data.nodes, which means that event data from Wiz should be within that path.

  1. Click the Send button to send the request.

    Group 37.png

RESULT

If the request is successful and the conditions for event creation are met, the ingested event can be viewed in D3 by navigating to Configuration > Data Ingestion and selecting the relevant webhook data ingestion job card (i.e., Webhook | Site: Security Operations within the Wiz accordion).

Group 38.png

Users can view the ingestion details by clicking the corresponding timestamp.

Group 39.png

Sending an API Key-Authenticated Request: Remote Command

The process of sending an API key-authenticated request is the same for utility and integration commands. Users should consult the specific command’s documentation for details on the commandParams object in the request body, as input parameters vary by command.

  1. Copy the request URL in vSOC.

    Group 23.png

  2. In Postman, set the HTTP request method to POST, then paste the request URL in the designated field.

    Group 24 (1).png

  3. In vSOC, copy the request header key.

    Group 25.png

  4. In Postman, click on the Headers tab, then paste the request header key under the Key column.

    Group 26.png

  5. In vSOC, copy the request header value.

    Group 27.png

  6. In Postman, paste the request header value under the Value column.

    Group 28.png

  7. In vSOC, copy the request body sample.

    Group 29.png

  8. In Postman, select the Body tab, choose the raw option, then paste the sample request body data.

    Group 20.png

  9. Adjust the values as necessary.

    replace with real value.gif

  10. Click the Send button to send the request.

    Group 30 (2).png

RESULT

A successful call with a valid response will resemble the following:

successful response.gif
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close