> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.

# External connections

An external connection is a Chronosphere Observability Platform configuration
object that stores credentials and connection details for a third-party system
used when sending alert notifications. Each external connection has a stable
`slug` that other resources use to refer to it. The display `name` can be
updated later, but the `slug` cannot be changed after creation.

## Supported integrations

In the [Chronosphere API](/tooling/api-info), the external connection resource
includes optional blocks for supported integration types. Each stored connection
configures one integration:

* Slack: API URL and token for posting messages.
* PagerDuty: Events API routing or service key for outbound alerts, an optional
  REST API token for related polling, and an Events API version selector.
* Webhook: target URL and optional HTTP settings such as basic authentication,
  bearer token, or TLS verification behavior.
* VictorOps: API key and API URL.
* OpsGenie: API key, API URL, and optional HTTP settings similar to a webhook
  connection.

You can create multiple external connections, including more than one for the
same integration type when you need separate credentials. Observability Platform
sets `created_at` and `updated_at`.

## Create an external connection

Select from the following methods to create an external connection.

<Tabs>
  <Tab title="Web" id="create-an-external-connection-web">
    Only [administrators](/administer/accounts-teams/user-accounts#grant-system-administrator-sysadmin-privileges-to-users) can create external connections.

    To create an external connection:

    1. In the navigation menu, select
       **<Icon icon="bell" /> Alerting <span aria-label="and then">></span>
       External Connections**.
    2. Click **Create connection**.
    3. In the **Create external connection** drawer, enter a **Name**.
    4. Select an **External connection type**.
    5. Complete the **Connection configuration** fields for the selected
       type.
    6. Click **Create**.
  </Tab>

  <Tab title="Chronoctl" id="create-an-external-connection-chronoctl">
    To create an external connection with [Chronoctl](/tooling/chronoctl):

    1. Run the following command to generate a sample configuration you can use
       as a template:

       ```shell theme={null}
       chronoctl external-connections scaffold
       ```

    2. Complete the definition file, then submit it:

       ```shell /FILE_NAME/ theme={null}
       chronoctl external-connections create -f FILE_NAME
       ```

       Replace *`FILE_NAME`* with the name of your YAML definition file.

    For flags such as `--dry-run`, use the same patterns as other configuration
    resources in [Configuration commands](/tooling/chronoctl#configuration-commands).
  </Tab>

  <Tab title="Terraform" id="create-an-external-connection-terraform">
    <Note>
      When you run `terraform plan` to generate an execution plan, Chronosphere automatically
      tests configurations that include notification policies by submitting them as dry runs.
      For details, see the
      [Terraform provider](/tooling/infrastructure/terraform#validate-plans-with-dry-runs)
      documentation.
    </Note>

    To create an external connection with [Terraform](/tooling/infrastructure/terraform),
    use an integration-specific resource type such as
    `chronosphere_slack_external_connection` or
    `chronosphere_pagerduty_external_connection`. Treat the Config API
    `ExternalConnection` schema in the [Chronosphere API](/tooling/api-info) reference
    as the canonical field description. For arguments that exist only in Terraform,
    consult the provider schema bundled with your version.

    1. Add the resource definition to a Terraform file.
    2. Run the following command to apply the changes:

       ```shell theme={null}
       terraform apply
       ```
  </Tab>

  <Tab title="API" id="create-an-external-connection-api">
    To create an external connection with the Chronosphere API, use the
    [`CreateExternalConnections`](/tooling/api-info/definition/operations/CreateExternalConnections)
    endpoint. Put the integration block under `external_connection`. Use the optional
    `dry_run` parameter to validate the request without persisting the connection.

    Because the Chronosphere API requires authentication, include an API token with your
    `curl` request, as shown in the following example. For more details, see
    [Create an API token](/tooling/api-info#create-an-api-token).

    ```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
    export CHRONOSPHERE_API_TOKEN="TOKEN"
    export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

    curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
         -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
    ```

    Replace the following:

    * *`TOKEN`*: Your API token.
    * *`INSTANCE`*: The subdomain name for your organization's Observability Platform instance.
    * *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
    * *`ENDPOINT_PATH`*: The specific endpoint you want to access.
  </Tab>
</Tabs>

## View external connections

Select from the following methods to view external connections.

<Tabs>
  <Tab title="Web" id="view-external-connections-web">
    In the navigation menu, select
    **<Icon icon="bell" /> Alerting <span aria-label="and then">></span>
    External Connections**.

    The **External Connections** page lists all connections with their
    type and name. Use **Filter by type** or **Search name** to narrow
    the list. Click a connection row to open it in the
    **Edit external connection** drawer.
  </Tab>

  <Tab title="Chronoctl" id="view-external-connections-chronoctl">
    To list all external connections with [Chronoctl](/tooling/chronoctl), use the
    following command:

    ```shell theme={null}
    chronoctl external-connections list
    ```

    To view a single connection by slug, use `read`:

    ```shell /SLUG/ theme={null}
    chronoctl external-connections read SLUG
    ```

    Replace *`SLUG`* with the slug of the connection you want to view.
  </Tab>

  <Tab title="Terraform" id="view-external-connections-terraform">
    [Use the Code Config tool](/tooling/gitops#use-the-code-config-tool) in
    Observability Platform to view the Terraform representation of an external
    connection.
  </Tab>

  <Tab title="API" id="view-external-connections-api">
    To list all external connections, use the
    [`ListExternalConnections`](/tooling/api-info/definition/operations/ListExternalConnections)
    endpoint.

    To retrieve a single connection by slug, use
    [`ReadExternalConnections`](/tooling/api-info/definition/operations/ReadExternalConnections).

    Because the Chronosphere API requires authentication, include an API token with your
    `curl` request, as shown in the following example. For more details, see
    [Create an API token](/tooling/api-info#create-an-api-token).

    ```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
    export CHRONOSPHERE_API_TOKEN="TOKEN"
    export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

    curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
         -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
    ```

    Replace the following:

    * *`TOKEN`*: Your API token.
    * *`INSTANCE`*: The subdomain name for your organization's Observability Platform instance.
    * *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
    * *`ENDPOINT_PATH`*: The specific endpoint you want to access.
  </Tab>
</Tabs>

## Update an external connection

Select from the following methods to update an external connection.

<Tabs>
  <Tab title="Web" id="update-an-external-connection-web">
    To update an external connection:

    1. In the navigation menu, select
       **<Icon icon="bell" /> Alerting <span aria-label="and then">></span>
       External Connections**.
    2. Click the connection you want to edit.
    3. In the **Edit external connection** drawer, update the connection
       fields. You can't change the connection type after creation.
    4. Click **Save**.
  </Tab>

  <Tab title="Chronoctl" id="update-an-external-connection-chronoctl">
    To update an external connection with [Chronoctl](/tooling/chronoctl):

    1. Edit the definition file for the connection.
    2. Run the following command to submit the changes:

       ```shell /FILE_NAME/ theme={null}
       chronoctl external-connections update -f FILE_NAME
       ```

       Replace *`FILE_NAME`* with the name of your YAML definition file.

    Chronoctl matches the connection to update by `slug`.
  </Tab>

  <Tab title="Terraform" id="update-an-external-connection-terraform">
    To update an external connection with [Terraform](/tooling/infrastructure/terraform):

    1. Edit the resource definition in your Terraform file.
    2. Run the following command to apply the changes:

       ```shell theme={null}
       terraform apply
       ```
  </Tab>

  <Tab title="API" id="update-an-external-connection-api">
    To update an external connection with the Chronosphere API, use the
    [`UpdateExternalConnections`](/tooling/api-info/definition/operations/UpdateExternalConnections)
    endpoint. The optional `create_if_missing` parameter creates the connection if no
    match for the slug exists. Use `dry_run` to validate without persisting.

    Because the Chronosphere API requires authentication, include an API token with your
    `curl` request, as shown in the following example. For more details, see
    [Create an API token](/tooling/api-info#create-an-api-token).

    ```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
    export CHRONOSPHERE_API_TOKEN="TOKEN"
    export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

    curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
         -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
    ```

    Replace the following:

    * *`TOKEN`*: Your API token.
    * *`INSTANCE`*: The subdomain name for your organization's Observability Platform instance.
    * *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
    * *`ENDPOINT_PATH`*: The specific endpoint you want to access.
  </Tab>
</Tabs>

## Delete an external connection

Select from the following methods to delete an external connection.

<Tabs>
  <Tab title="Web" id="delete-an-external-connection-web">
    Only administrators can delete external connections.

    To delete an external connection:

    1. In the navigation menu, select
       **<Icon icon="bell" /> Alerting <span aria-label="and then">></span>
       External Connections**.
    2. Click the connection you want to delete.
    3. In the **Edit external connection** drawer, click
       **Delete external connection**.
    4. Click **Delete** to confirm.
  </Tab>

  <Tab title="Chronoctl" id="delete-an-external-connection-chronoctl">
    To delete an external connection with [Chronoctl](/tooling/chronoctl):

    ```shell /SLUG/ theme={null}
    chronoctl external-connections delete SLUG
    ```

    Replace *`SLUG`* with the slug of the connection you want to delete.
  </Tab>

  <Tab title="Terraform" id="delete-an-external-connection-terraform">
    To delete a resource that's managed by [Terraform](/tooling/infrastructure/terraform):

    1. Edit your Terraform configuration file to remove the pre-existing resource
       definition.
    2. Run this command to remove the resource from Observability Platform:

       ```shell theme={null}
       terraform apply
       ```
  </Tab>

  <Tab title="API" id="delete-an-external-connection-api">
    To delete an external connection with the Chronosphere API, use the
    [`DeleteExternalConnections`](/tooling/api-info/definition/operations/DeleteExternalConnections)
    endpoint.

    Because the Chronosphere API requires authentication, include an API token with your
    `curl` request, as shown in the following example. For more details, see
    [Create an API token](/tooling/api-info#create-an-api-token).

    ```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
    export CHRONOSPHERE_API_TOKEN="TOKEN"
    export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

    curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
         -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
    ```

    Replace the following:

    * *`TOKEN`*: Your API token.
    * *`INSTANCE`*: The subdomain name for your organization's Observability Platform instance.
    * *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
    * *`ENDPOINT_PATH`*: The specific endpoint you want to access.
  </Tab>
</Tabs>

## Notification policies and external connections

[Notification policies](/investigate/alerts/notifications/policies) route alerts
to recipients. In the Chronosphere API, each severity on a route uses a notifier
list. For the notification policy JSON shape in the Config API, see
[`ReadNotificationPolicy`](/tooling/api-info/definition/operations/ReadNotificationPolicy).
That list can reference existing notifier resources by `notifier_slugs`, or define
inline `destinations` that reference external connections. You can't set both on
the same notifier list.

For all notifiers except email, each destination sets `external_connection_slug`
to the slug of an external connection that stores the credentials for that
delivery. For email, set `addresses` only without referencing an external
connection.

Observability Platform validates that every `external_connection_slug` you
reference exists before accepting the policy.

Field-level routing for policies appears in
[External connections and route destinations](/investigate/alerts/notifications/policies#external-connections-and-route-destinations).

## Lifecycle and safety

Deleting an external connection fails if a notification policy or other
resource still references its slug, so credentials remain addressable until
you remove those references.

## Notifier resource migration

While you still use `notifier_slugs`, separate notifier resources apply. Field
reference for that model lives under
[Notifiers](/investigate/alerts/notifications/notifiers), including
[Slack](/investigate/alerts/notifications/notifiers/slack),
[PagerDuty](/investigate/alerts/notifications/notifiers/pagerduty),
[Webhook](/investigate/alerts/notifications/notifiers/webhook),
[VictorOps](/investigate/alerts/notifications/notifiers/victorops), and
[OpsGenie](/investigate/alerts/notifications/notifiers/opsgenie). To move a route
to external connections, create connections for those credentials, switch the
route to `destinations` and `external_connection_slug`, then drop `notifier_slugs`
one notifier list at a time.