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

# Tailscale

> Connect Tailscale to Clarion to receive network and identity events — device approvals, key expiry, policy changes, and user lifecycle — as issues.

This guide explains how to connect Tailscale to Clarion. Once configured, Clarion receives Tailscale webhook events and opens issues that agents can triage and investigate.

<Note>
  **Estimated time:** 5-10 minutes. You will need **Tailscale Owner or Admin** access and access to the Clarion workspace where you want to connect Tailscale.
</Note>

## Prerequisites

* A Tailscale account with Owner or Admin role
* Access to the Clarion workspace where you want to configure the integration

## Add a Tailscale monitor in Clarion

The Tailscale webhook is configured as a **monitor**, so each one has its own URL and signing secret.

1. Open Clarion and go to **Integrations** → **Tailscale**.
2. In the **Monitors** section, click **Add monitor** and choose **Tailscale**.
3. Copy the generated **Webhook URL** and **Secret** shown on the monitor. You will paste these into Tailscale in the next step.

## Configure the webhook in Tailscale

1. Sign in to the [Tailscale admin console](https://login.tailscale.com/admin).
2. Navigate to **Settings** → **Webhooks**.
3. Click **Add endpoint**.
4. Paste the **Webhook URL** from Clarion into the **Endpoint URL** field.
5. Paste the **Secret** from Clarion into the **Secret** field.
6. Select the event types you want to receive. Clarion handles all Tailscale event types:
   * **Device events**: `nodeNeedsApproval`, `nodeApproved`, `nodeKeyExpiringSoon`, `nodeKeyExpiryDisabled`, `nodeKeyExpiryEnabled`, `nodeNotSeen`
   * **Policy events**: `policyUpdate`
   * **User events**: `userNeedsApproval`, `userApproved`, `userSuspended`, `userRoleUpdated`, `userCreated`, `userDeleted`
7. Click **Save**.
8. Use **Send test event** to verify the connection. Clarion will create a test alert to confirm delivery.

## Enable agent tools (API access)

Beyond receiving events, you can let Clarion agents act on your tailnet — investigating devices, users, keys, DNS, and ACL policy, and (with approval) running remediation such as deauthorizing a device or suspending a user. This uses a Tailscale **OAuth client**; the client secret is stored encrypted and is never exposed to agents.

1. Sign in to the [Tailscale admin console](https://login.tailscale.com/admin).
2. Go to **Settings** → **OAuth clients** and click **Generate OAuth client**.
3. Grant the client the scopes for the capabilities you want. The minimal set for the full tool suite is:

   * `devices:core` — list/get devices, authorize/deauthorize, expire, set tags
   * `devices:routes:read` — list device subnet routes
   * `auth_keys:read` — list auth keys
   * `users` — list/get users, suspend/restore
   * `dns:read` — read DNS nameservers, preferences, and search paths
   * `policy_file:read` — read the ACL policy file
   * `account_settings:read` — read tailnet contacts

   Grant only the scopes you need — for read-only investigation, use the `:read` scopes and omit `devices:core` and `users`.
4. Copy the **Client ID** and **Client secret** (the secret is shown only once).
5. In Clarion, go to **Integrations** → **Tailscale** → **API access (agent tools)**, paste the Client ID and secret, and click **Save**. Leave **Tailnet** blank to use the OAuth client's default tailnet.

<Note>
  The five write actions — authorize/deauthorize a device, set device tags, expire a device, and suspend/restore a user — require explicit human approval before an agent can run them. You can review and adjust approval requirements per tool under **Settings** → **Tools**.
</Note>

## How severity is mapped

| Event                                                                            | Severity |
| -------------------------------------------------------------------------------- | -------- |
| `nodeNotSeen`, `userSuspended`, `nodePolicyViolation`                            | Critical |
| `nodeNeedsApproval`, `userNeedsApproval`                                         | High     |
| `policyUpdate`, `userRoleUpdated`, `nodeKeyExpiringSoon`, `nodeKeyExpiryEnabled` | Medium   |
| All other events                                                                 | Low      |

## Verifying the connection

After saving the webhook in Tailscale, send a test event from the Tailscale admin console. A test issue will appear in Clarion under **Issues**, confirming the integration is working.