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

# Connections

> Connect third-party apps like Slack, GitHub, and Stripe once, then use their operations as workflow nodes — credentials stay encrypted and are injected at runtime.

# Connections

A **connection** is a saved, encrypted credential for a third-party app. Connect an app once, then drop its operations into any workflow as action nodes — KnoxCall injects the credentials at runtime and calls the provider through its hardened, SSRF-pinned transport. Your secrets are never stored in a workflow definition and never appear in logs.

## Catalog

Ten apps ship in the connector catalog:

| App          | Auth          | Example operations                 |
| ------------ | ------------- | ---------------------------------- |
| **SendGrid** | API key       | Send Email                         |
| **Stripe**   | API key       | Create Customer, event trigger     |
| **Twilio**   | API key       | Send SMS                           |
| **Slack**    | OAuth         | Send Message, new-message polling  |
| **GitHub**   | OAuth         | Create Issue, issue-opened trigger |
| **Notion**   | API key       | Create Database Page               |
| **Linear**   | API key       | Create Issue                       |
| **Discord**  | Bot token     | Send Message                       |
| **Airtable** | API key (PAT) | Create Record                      |
| **Telegram** | Bot token     | Send Message                       |

Each operation appears in the builder's **Apps** palette category and, once added, references a connection you select in the node inspector.

## Creating a Connection

1. Go to **Workflows → Connections** (or **Connections** in the sidebar).
2. Click **New Connection** and pick an app.
3. Provide credentials:
   * **API-key / token apps** (SendGrid, Stripe, Twilio, Notion, Linear, Discord, Airtable, Telegram): paste the key. KnoxCall **verifies it against the real provider** before saving, so a bad key fails fast.
   * **OAuth apps** (Slack, GitHub): click **Connect** to open the provider's consent screen in a popup. On approval the window closes and the connection goes **active**.
4. The connection is saved encrypted (envelope encryption, per tenant). Only masked metadata is ever shown back — the raw secret is write-only.

<Note>
  Connections are scoped by mode (**Live** / **Test**) just like the rest of
  KnoxCall. A Test-mode workflow can only use Test-mode connections.
</Note>

## Using a Connection in a Workflow

1. In the builder, open the **Apps** category in the node palette and add an operation (e.g. *Slack → Send Message*).
2. In the inspector, choose the **Connection** to use.
3. Fill in the operation's fields — they support `{{ ... }}` variables like any other node.

At runtime the connector calls the provider over an exact-host-allowlisted HTTPS transport with a per-app rate limit. If an OAuth token has expired, the connector refreshes it once and retries automatically.

## OAuth: Managed vs. Bring-Your-Own Client

For OAuth apps, KnoxCall needs a registered OAuth client with the provider:

* **Cloud (knoxcall.com):** KnoxCall manages a platform OAuth client for each supported app — just click **Connect**.
* **Self-hosted / BYO:** register your own OAuth app with the provider and enter its client ID/secret under the app's settings. Your client takes precedence over any platform default. This is required on self-hosted installs and whenever a "needs BYO client" prompt appears.

The OAuth redirect URL is a single per-environment endpoint (`https://knoxcall.com/oauth/apps/callback` and its staging twin); the specific app and connection are carried in a signed, encrypted state parameter, so you don't register a URL per app.

## Connection Health

* **Reauthorize** — if a provider revokes access or a token can't refresh, the connection moves to **error**; use **Reauthorize** to fix it.
* **Automatic refresh** — refreshable OAuth tokens are renewed ahead of expiry by a background lease.
* **Health sweep** — connections not checked in over 24 hours are re-verified in the background, so silently-revoked credentials surface as errors before a workflow run hits them.

## Security

* Credentials are **envelope-encrypted per tenant** and write-only; the UI shows only masked metadata.
* All connector traffic goes through the same SSRF-pinned egress as the rest of KnoxCall, restricted to each provider's exact hostnames.
* Secret values are redacted everywhere they could surface — step logs, the run overlay, and execution details.

## Next Steps

<CardGroup cols={2}>
  <Card title="Triggers" icon="bolt" href="/workflows/triggers">
    Fire workflows from app events
  </Card>

  <Card title="Creating Workflows" icon="plus" href="/workflows/creating-workflows">
    Build a workflow that uses a connection
  </Card>
</CardGroup>