Connectors API¶

The Connectors API manages connector configurations that bind agents to external systems. Each connector configuration defines the connector type, the set of permitted operations (INV-005 scope binding), and encrypted credentials. The API also provides an execution endpoint that runs connector operations through the policy engine with full audit logging.

All endpoints are scoped to the authenticated user's organization via Row-Level Security.

Get Connector Schemas¶

Returns credential schemas for all supported connector types. Use this to determine which credential fields are required when creating or updating a connector configuration.

• Method: GET
• Path: /v1/connectors/schemas
• Required Role: Any authenticated user

Example¶

curl -X GET "https://api.arxsec.io/v1/connectors/schemas" \
  -H "Authorization: Bearer {token}"

Response¶

Returns a JSON object keyed by connector type. Each entry defines the required and optional credential fields with their types, descriptions, and defaults.

{
  "crowdstrike": {
    "fields": {
      "client_id": { "type": "string", "required": true, "description": "OAuth2 client ID" },
      "client_secret": { "type": "string", "required": true, "sensitive": true, "description": "OAuth2 client secret" },
      "base_url": { "type": "string", "required": false, "default": "https://api.crowdstrike.com" }
    }
  }
}

List Connector Configurations¶

Retrieves connector configurations for the organization, optionally filtered by agent.

• Method: GET
• Path: /v1/connectors
• Required Role: Any authenticated user

Query Parameters¶

Response¶

{
  "configs": [
    {
      "id": "c1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "org_id": "org-uuid",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "connector_type": "crowdstrike",
      "permitted_operations": ["detections:read", "hosts:read"],
      "credentials_configured": true,
      "credentials_redacted": {
        "client_id": "abc1...****",
        "client_secret": "****",
        "base_url": "https://api.crowdstrike.com"
      },
      "created_at": "2026-03-18T12:00:00Z",
      "updated_at": "2026-03-18T12:00:00Z"
    }
  ],
  "total": 1
}

Credential values are always redacted in responses. Sensitive fields show ****. Non-sensitive fields show a truncated prefix.

Example¶

curl -X GET "https://api.arxsec.io/v1/connectors?agent_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}"

Create Connector Configuration¶

Creates a connector configuration with scoped permissions and optional encrypted credentials.

• Method: POST
• Path: /v1/connectors
• Required Role: admin or deployer

Request Body¶

Example¶

curl -X POST "https://api.arxsec.io/v1/connectors" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "connector_type": "crowdstrike",
    "permitted_operations": ["detections:read", "hosts:read"],
    "credentials": {
      "client_id": "abc123def456",
      "client_secret": "secret-value-here"
    }
  }'

Response¶

Returns the created connector configuration with HTTP status 201 Created. Credentials are validated against the connector schema before storage. Invalid credentials return 400 with an errors array. The creation is audit-logged with the connector type and permitted operations.

Update Connector Configuration¶

Updates a connector configuration's permitted operations or credentials.

• Method: PATCH
• Path: /v1/connectors/{config_id}
• Required Role: admin or deployer

Path Parameters¶

Request Body¶

All fields are optional. Only provided fields are updated.

Example¶

curl -X PATCH "https://api.arxsec.io/v1/connectors/c1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "permitted_operations": ["detections:read", "hosts:read", "hosts:contain"]
  }'

Response¶

Returns the updated connector configuration. Returns 400 if no fields are provided or credentials are invalid. Returns 404 if the configuration is not found.

Delete Connector Configuration¶

Deletes a connector configuration.

• Method: DELETE
• Path: /v1/connectors/{config_id}
• Required Role: admin or deployer

Path Parameters¶

Example¶

curl -X DELETE "https://api.arxsec.io/v1/connectors/c1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}"

Response¶

Returns HTTP status 204 No Content on success. Returns 404 if the configuration is not found. The deletion is audit-logged with the connector type.

Execute Connector Operation¶

Executes a connector operation through the policy engine. The operation is validated against the connector's permitted operations, evaluated by the policy engine for risk scoring, and fully audit-logged.

• Method: POST
• Path: /v1/connectors/{config_id}/execute
• Required Role: admin or deployer

Path Parameters¶

Request Body¶

Example¶

curl -X POST "https://api.arxsec.io/v1/connectors/c1b2c3d4-e5f6-7890-abcd-ef1234567890/execute" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "detections:read",
    "params": {
      "filter": "severity:Critical",
      "limit": 50
    }
  }'

Response¶

{
  "status": "success",
  "result": {
    "detections": [ ... ],
    "total": 12
  }
}

Possible status values:

Returns 403 if the operation is not in the connector's permitted_operations. Returns 400 if no credentials are configured. Returns 404 if the configuration is not found.