> ## 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.

# Pylon

> Connect Pylon to Clarion so agents can read customer-support issues, message threads, and accounts — and triage the issues your Pylon triggers send over.

This guide walks you through connecting your Pylon workspace to Clarion. Once connected, Clarion gives your agents read access to your support desk during any investigation, and — if you add a monitor — turns the issues your Pylon triggers select into issues an agent triages.

<Note>
  **Estimated time:** 5 minutes. You will need permission to create a **Pylon API token**, and, for the monitor, permission to edit **Webhooks** and **Triggers** in Pylon settings.
</Note>

## Prerequisites

* A **Pylon account** with access to Settings
* A **Clarion workspace** with the Pylon integration open

***

## Step 1 — Create an API token in Pylon

1. In Pylon, go to **Settings → API tokens**.
2. Create a token and copy it.

The token is organization-wide: Clarion reads and writes exactly what that token is allowed to, which is the same scope as the Pylon dashboard. Actions Clarion takes appear in Pylon under the token's name, so give it a name you will recognise in an audit trail — `Clarion`, for example.

<Warning>
  Copy the token immediately — Pylon shows it only once.
</Warning>

***

## Step 2 — Connect in Clarion

1. In Clarion, open the **Pylon integration** from your workspace settings.
2. Choose your **Region** — `api.usepylon.com` for the United States or `api.eu.usepylon.com` for Europe. A token only works in the region its workspace is hosted in, and there is no way to detect that from the token itself, so pick the one you sign in to.
3. Paste the **API token**.
4. Click **Connect**.

Clarion verifies the token against Pylon before saving it, so a mistyped token or the wrong region is reported straight away rather than failing quietly on the first agent run. Once connected, the page names the Pylon organization the token belongs to — a quick way to confirm you connected the workspace you meant to.

***

## Step 3 — Add a Pylon monitor

The integration on its own gives your agents lookups. To have an agent triage support issues as they arrive, add a **Pylon** monitor:

1. Open the agent you want to receive Pylon issues.
2. Add a **Pylon** monitor.
3. Set the **Default severity**. Pylon issues carry no severity of their own, so this is the level Clarion applies unless your trigger's body includes a `priority` field.
4. Clarion generates a webhook URL and a one-time secret. Copy both — the secret is shown once.

***

## Step 4 — Send issues from Pylon

Pylon delivers webhooks in two parts: an **endpoint** that says where to send and what headers to attach, and a **trigger** that decides when to fire.

**Add the endpoint.**

1. In Pylon, go to **Settings → Webhooks**.
2. Add an endpoint with the URL Clarion generated.
3. Add a custom header named `Authorization` with the value `Bearer <secret>`, using the secret Clarion showed you.

Clarion rejects any delivery without that header, so nobody who finds the URL can post issues into your workspace.

**Add the trigger.**

1. Go to **Settings → Triggers** and create a trigger whose action is **Send webhook**, pointed at the endpoint you just added.
2. Use the trigger's **When** and **If** conditions to choose which issues an agent should triage. A trigger that fires on every issue will send your whole support volume to Clarion, so start narrow — a tag, a priority, or a specific queue.
3. Set the webhook body to include the issue id:

```json theme={null}
{ "issue_id": "{{issue.id}}" }
```

That is all Clarion needs. It reads the issue's title, state, account, requester, tags, and body back from Pylon using the API token from Step 2, so the issue an agent sees is always the current one rather than a snapshot of whatever the template produced. A richer body still works — Clarion keeps the whole delivery on the issue so you can see exactly what Pylon sent.

<Note>
  If your body includes a `priority` field (`urgent`, `high`, `medium`, or `low`), Clarion maps it onto the issue's severity instead of using the monitor's default.
</Note>

***

## What your agents can do

With Pylon connected, agents triaging *any* issue — not only Pylon ones — can:

* **Search issues** — by text, state, account, assignee, team, tags, or date range
* **Read an issue** — full detail, including account, requester, tags, custom fields, and SLA breach times
* **Read a message thread** — the whole conversation, with internal notes marked as private
* **Search accounts** — by name, domain, or tag
* **Read an account** — domains, tags, owner, and custom field values
* **Look up a contact or a team member** — to turn an id on an issue into a named person

Agents can also **open an issue**, **update an issue**, and **update an account**. These change what a customer sees, so they run through your workspace's tool-approval policy — configure it under **Settings → Tools**.

***

## Troubleshooting

**"Pylon rejected the API token."** The token is wrong, or the region does not match the workspace you sign in to. Check the region first — it is the most common cause.

**No issues appearing.** Confirm a Pylon monitor exists and is attached to an agent, that your trigger's conditions actually match the issues you expect, and that the endpoint the trigger points at is the one carrying the `Authorization` header.

**Deliveries rejected.** Check the `Authorization` header on the Pylon endpoint. It must read `Bearer ` followed by the secret, with no extra whitespace. If you have lost the secret, rotate it on the monitor and paste the new one into Pylon.

**Issues arrive without a title or detail.** Clarion could not match the delivery to a Pylon issue, so it ingested the raw body instead — the issue's description shows exactly what arrived. Check that the trigger's body includes the issue id, and that the integration is still connected.

**Rotating the secret.** Open the monitor and rotate it, then update the `Authorization` header in Pylon. Deliveries carrying the old secret are rejected from the moment you rotate, so change both in quick succession.