kibana-connectors

What this skill does

# Kibana Connectors

## Core Concepts

Connectors store connection information for Elastic services and third-party systems. Alerting rules use connectors to
route **actions** (notifications) when rule conditions are met. Connectors are managed per **Kibana Space** and can be
shared across all rules within that space.

### Connector Categories

| Category                    | Connector Types                                                                                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **LLM Providers**           | OpenAI, Google Gemini, Amazon Bedrock, Elastic Managed LLMs, AI Connector, MCP (Preview, 9.3+)                                                                       |
| **Incident Management**     | PagerDuty, Opsgenie, ServiceNow (ITSM, SecOps, ITOM), Jira, Jira Service Management (9.2+), IBM Resilient, Swimlane, Torq, Tines, D3 Security, XSOAR (9.1+), TheHive |
| **Endpoint Security**       | CrowdStrike, SentinelOne, Microsoft Defender for Endpoint                                                                                                            |
| **Messaging**               | Slack (API / Webhook), Microsoft Teams, Email                                                                                                                        |
| **Logging & Observability** | Server log, Index, Observability AI Assistant                                                                                                                        |
| **Webhook**                 | Webhook, Webhook - Case Management, xMatters                                                                                                                         |
| **Elastic**                 | Cases                                                                                                                                                                |

## Authentication

All connector API calls require API key auth or Basic auth. Every mutating request must include the `kbn-xsrf` header.

```http
kbn-xsrf: true
```

## Required Privileges

Access to connectors is granted based on your privileges to alerting-enabled features. You need `all` privileges for
Actions and Connectors in Stack Management.

## API Reference

Base path: `<kibana_url>/api/actions` (or `/s/<space_id>/api/actions` for non-default spaces).

| Operation           | Method | Endpoint                               |
| ------------------- | ------ | -------------------------------------- |
| Create connector    | POST   | `/api/actions/connector/{id}`          |
| Update connector    | PUT    | `/api/actions/connector/{id}`          |
| Get connector       | GET    | `/api/actions/connector/{id}`          |
| Delete connector    | DELETE | `/api/actions/connector/{id}`          |
| Get all connectors  | GET    | `/api/actions/connectors`              |
| Get connector types | GET    | `/api/actions/connector_types`         |
| Run connector       | POST   | `/api/actions/connector/{id}/_execute` |

## Creating a Connector

### Required Fields

| Field               | Type   | Description                                                                      |
| ------------------- | ------ | -------------------------------------------------------------------------------- |
| `name`              | string | Display name for the connector                                                   |
| `connector_type_id` | string | The connector type (e.g., `.slack`, `.email`, `.webhook`, `.pagerduty`, `.jira`) |
| `config`            | object | Type-specific configuration (non-secret settings)                                |
| `secrets`           | object | Type-specific secrets (API keys, passwords, tokens)                              |

### Example: Create a Slack Connector (Webhook)

```bash
curl -X POST "https://my-kibana:5601/api/actions/connector/my-slack-connector" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey <your-api-key>" \
  -d '{
    "name": "Production Slack Alerts",
    "connector_type_id": ".slack",
    "config": {},
    "secrets": {
      "webhookUrl": "https://hooks.slack.com/services/T00/B00/XXXX"
    }
  }'
```

All connector types share the same request structure — only `connector_type_id`, `config`, and `secrets` differ. See the
[Common Connector Type IDs](#common-connector-type-ids) table for available types and their required fields.

### Example: Create a PagerDuty Connector

```bash
curl -X POST "https://my-kibana:5601/api/actions/connector/my-pagerduty" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey <your-api-key>" \
  -d '{
    "name": "PagerDuty Incidents",
    "connector_type_id": ".pagerduty",
    "config": {
      "apiUrl": "https://events.pagerduty.com/v2/enqueue"
    },
    "secrets": {
      "routingKey": "your-pagerduty-integration-key"
    }
  }'
```

## Updating a Connector

`PUT /api/actions/connector/{id}` replaces the full configuration. `connector_type_id` is immutable — delete and
recreate to change it.

## Listing and Discovering Connectors

```bash
# Get all connectors in the current space
curl -X GET "https://my-kibana:5601/api/actions/connectors" \
  -H "Authorization: ApiKey <your-api-key>"

# Get available connector types
curl -X GET "https://my-kibana:5601/api/actions/connector_types" \
  -H "Authorization: ApiKey <your-api-key>"

# Filter connector types by feature (e.g., only those supporting alerting)
curl -X GET "https://my-kibana:5601/api/actions/connector_types?feature_id=alerting" \
  -H "Authorization: ApiKey <your-api-key>"
```

The `GET /api/actions/connectors` response includes `referenced_by_count` showing how many rules use each connector.
Always check this before deleting.

## Running a Connector (Test)

Execute a connector action directly, useful for testing connectivity.

```bash
curl -X POST "https://my-kibana:5601/api/actions/connector/my-slack-connector/_execute" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey <your-api-key>" \
  -d '{
    "params": {
      "message": "Test alert from API"
    }
  }'
```

## Deleting a Connector

```bash
curl -X DELETE "https://my-kibana:5601/api/actions/connector/my-slack-connector" \
  -H "kbn-xsrf: true" \
  -H "Authorization: ApiKey <your-api-key>"
```

**Warning:** Deleting a connector that is referenced by rules will cause those rule actions to fail silently. Check
`referenced_by_count` first.

## Terraform Provider

Use the `elasticstack` provider resource `elasticstack_kibana_action_connector`.

```hcl
terraform {
  required_providers {
    elasticstack = {
      source  = "elastic/elasticstack"
    }
  }
}

provider "elasticstack" {
  kibana {
    endpoints = ["https://my-kibana:5601"]
    api_key   = var.kibana_api_key
  }
}

resource "elasticstack_kibana_action_connector" "slack" {
  name              = "Production Slack Alerts"
  connector_type_id = ".slack"

  config = jsonencode({})

  secrets = jsonencode({
    webhookUrl = "https://hooks.slack.com/services/T00/B00/XXXX"
  })
}

resource "elasticstack_kibana_action_connector" "index" {
  name              = "Alert Index Writer"
  connector_type_id = ".index"

  config = jsonencode({
    index              = "alert-history"
    executionTimeField = "@timestamp"
  })

  secrets = jsonencode({})
}
```

**Key Terraform notes:**

- `config` and `secrets` must be JSON-encoded strings via `jsonencode()`
- Secrets are stored in Terraform state; use a remote backend with encryption and restrict state file access
- Import existing connectors:
  `terraform import elasticstack_kibana_action_connector.my_connector <space_id>/<connector_id>` (use `defaul