Octo Integration

This document describes the usage, configuration, and validation steps for the Octo integration endpoint in Data Touch.

Overview¶

The Octo Integration enables external systems to retrieve environment-level metadata and sensitivity insights from Data Touch via a secure REST API. It is designed to support filtering, monitoring, and reporting use cases by exposing environment information in a structured format.

Endpoint Details¶

Method: POST
Path: /api/data-touch/octo/integration/v1/environments/search
Authentication: Required via X-API-CLIENT and X-API-KEY headers

Note

The values for X-API-CLIENT and X-API-KEY must be predefined in the system environment variables during the installation process.
Access Control: This endpoint is restricted by IP whitelisting. The requesting client's IP address must be defined in the ALLOWED_IPS (or OCTO_CLIENT_ALLOWED_IPS) field within the environment configuration.
Pagination: Not supported
Response Type: Direct list (List<OctoEnvironmentResponseDto>)

Authentication & Headers¶

The endpoint is secured a global API key filter.

Required Headers¶

X-API-CLIENT: (e.g., octo-client)
X-API-KEY: The secret key defined in environment variables
Content-Type: application/json

Request Body¶

All fields are optional. If an empty body ({}) is sent, the endpoint returns results based on the default filter configuration.

Example Request¶

JSON

{
  "projectId": "91",
  "envType": "SINGLE",
  "agentStatus": true
}

Request Parameters (Supported Filters)¶

These fields are used in the POST request body to filter the results. All fields are optional.

Field	Type	Description	Example
`envType`	String	Environment topology. Values: `SINGLE`, `CLUSTER`.	`"SINGLE"`
`databaseType`	String	The database vendor.	`"oracle"`
`databaseName`	String	Logical name of the database.	`"test_db"`
`projectId`	String	Unique identifier of the project.	`"1"`
`projectName`	String	Name of the project.	`"Finance_App"`
`dataEnvId`	String	Unique identifier of the data environment.	`"109"`
`dataEnvName`	String	Display name of the data environment.	`"Production_Primary"`
`agentStatus`	Boolean	Filter by the agent's connection status.	`true`
`lastScanDateFrom`	String (ISO)	Start date filter for the last scan (inclusive).	`"2026-01-01T00:00:00"`
`lastScanDateTo`	String (ISO)	End date filter for the last scan (inclusive).	`"2026-05-01T23:59:59"`

Response Fields (Data Model)¶

The API returns a list of objects with the following structure:

Field	Type	Description
`id`	Integer	Internal unique ID of the environment record.
`type`	String	Integration category (e.g., `SDM`, `Radar`).
`envType`	String	Topology of the environment.
`clusterName`	String	Name of the cluster (`null` if `envType` is `SINGLE`).
`databaseType`	String	Database engine (e.g., `oracle`, `postgresql`, `mysql`).
`databaseName`	String	Name of the database instance.
`hostname`	String	Resolved hostname of the server.
`serverIp`	String	IPv4 address of the database server.
`serverPort`	String	Network port of the database service.
`agentStatus`	Boolean	Current health status of the Data Touch agent.
`projectId`	String	The ID of the associated project.
`projectName`	String	The name of the associated project.
`sensitiveTypeCount`	Integer	Total count of unique sensitive data types discovered.
`sensitiveTypeColumnCount`	Integer	Total count of columns containing sensitive data.
`columnCount`	Integer	Total number of columns scanned in the environment.
`sensitiveTypeNames`	String	Comma-separated list of identified PII/sensitive data types.
`dataEnvId`	String	ID of the linked data environment.
`dataEnvName`	String	Name of the linked data environment.
`lastScanDate`	String (ISO)	Timestamp of the most recent sensitivity scan.
`nodes`	Array	List of associated node metadata.
`radarNodes`	Integer	Count of total radar nodes detected.
`monitoredRadarNodes`	Integer	Count of radar nodes currently under monitoring.

Response Example¶

JSON

[
  {
    "id": 1001,
    "type": "SDM",
    "envType": "SINGLE",
    "clusterName": null,
    "databaseType": "postgresql",
    "databaseName": "PROD_DB_MOCK",
    "hostname": "db.example.com",
    "serverIp": "10.0.0.15",
    "serverPort": "5432",
    "agentStatus": true,
    "projectId": "42",
    "projectName": "E-Commerce_Module",
    "sensitiveTypeCount": 5,
    "sensitiveTypeColumnCount": 12,
    "columnCount": 150,
    "sensitiveTypeNames": "Full Name, Email Address, Phone Number, Credit Card, IP Address",
    "dataEnvId": "202",
    "dataEnvName": "Customer_Production_Mirror",
    "lastScanDate": "2026-05-01T10:00:00",
    "nodes": [],
    "monitoredRadarNodes": 0,
    "radarNodes": 0
  }
]

cURL Examples¶

Filtered Request¶

Bash

curl --location 'https://datatouch.netfein.com/api/data-touch/...' \
--header 'Content-Type: application/json' \
--header 'X-API-CLIENT: octo-client' \
--header 'X-API-KEY: <OCTO_CLIENT_KEY>' \
--data '{
  "projectId": "91",
  "envType": "SINGLE",
  "agentStatus": true
}'

Unfiltered Request¶

Bash

curl --location 'https://datatouch.netfein.com/api/data-touch/...' \
--header 'Content-Type: application/json' \
--header 'X-API-CLIENT: octo-client' \
--header 'X-API-KEY: <OCTO_CLIENT_KEY>' \
--data '{}'

401 Authentication Test (Intentional Failure)¶

Bash

curl --location 'https://datatouch.netfein.com/api/data-touch/...' \
--header 'Content-Type: application/json' \
--header 'X-API-CLIENT: octo-client' \
--header 'X-API-KEY: wrong-key' \
--data '{}'

Configuration¶

Ensure the following configurations are properly set before using the integration:

Enable API Key Filtering¶

Text Only

API_KEY_ENABLED=true

Octo Integration Settings¶

Text Only

OCTO_CLIENT_ENABLED=true
OCTO_CLIENT_KEY=octo-client-secret-key
OCTO_CLIENT_ALLOWED_IPS=10.20.30.40,10.20.30.41

Allowlist Endpoint¶

The endpoint path must be defined in the API key allowlist:

Text Only

/api/data-touch/octo/integration/v1/environments/search

Integration Workflow¶

To successfully integrate with the Octo endpoint, follow these steps:

Infrastructure
Ensure your IP address is included in the OCTO_CLIENT_ALLOWED_IPS configuration.
Authentication
Obtain your OCTO_CLIENT_KEY from the environment configuration.
Request Execution
Send a POST request to the endpoint with the required headers.

Data Filtering (Request Parameters)¶

Parameter	Type	Description	Example
`projectId`	String	Filter by a specific project ID.	`"91"`
`envType`	Enum	Connection topology: `SINGLE` or `CLUSTER`.	`"SINGLE"`
`agentStatus`	Boolean	Filter by active or inactive agents.	`true`

Status Codes¶

Code	Message	Description
`200 OK`	Success	Request was successful and results are returned.
`400 Bad Request`	Invalid Input	The request body is malformed or contains invalid fields.
`401 Unauthorized`	Auth Failed	Invalid API key, client ID, or IP address is not whitelisted.
`500 Internal Error`	Server Error	An unexpected error occurred on the Data Touch side.

Best Practices¶

Security
Never hardcode the X-API-KEY in frontend applications or public repositories. Always implement backend-to-backend communication for secure integration.
Empty Request Bodies
Sending an empty body ({}) is supported; however, it may return a large dataset. For better performance, it is recommended to apply at least one filter (e.g., projectId).
Date Format
The lastScanDate field follows the ISO-8601 format (YYYY-MM-DDTHH:mm:ss). Ensure all date-based filters use this format.

Troubleshooting¶

401 Unauthorized¶

If you receive a 401 Unauthorized response, verify the following:

X-API-CLIENT is set to octo-client
X-API-KEY exactly matches OCTO_CLIENT_KEY
API_KEY_ENABLED=true is configured and active