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

# Connecting a Source

> How to connect an external data source to Causeloop — via the UI or the API — including the OAuth authorization flow.

You can connect a new source in about two minutes from the Causeloop UI. For automation or CI/CD pipelines, the same flow is available via the API.

## Connect via the UI

<Steps>
  <Step title="Open the Integrations page">
    Go to **Settings → Integrations** in the sidebar, or navigate directly to `https://app.causeloop.ai/integrations`. You'll see the connector catalog grouped by category.
  </Step>

  <Step title="Choose a connector">
    Click the connector you want to add. The detail panel shows what the connector ingests, what permissions it needs, and whether it uses OAuth or an API key.
  </Step>

  <Step title="Name your connection">
    Give the connector an optional display name (e.g. "Production PagerDuty"). This is how it appears in sync logs and webhook filters.
  </Step>

  <Step title="Authenticate">
    **OAuth connectors** — click **Authorize**. Causeloop opens the provider's login page in a new window. Sign in and grant the requested scopes. You're redirected back to Causeloop when complete.

    **API key connectors** — paste your API key (or service account token) into the credentials field and click **Save**.
  </Step>

  <Step title="Test the connection">
    Causeloop automatically tests the connection after saving. A green checkmark means the credentials are valid and the connector can reach the provider. If the test fails, double-check the credentials and retry.
  </Step>

  <Step title="Configure the sync schedule (optional)">
    By default, connectors sync every 30 minutes. Open the **Schedule** tab to change the frequency or set a custom cron expression. You can also trigger an immediate sync or a historical backfill from this panel.
  </Step>

  <Step title="Start syncing">
    The connector is now active. Causeloop starts an initial backfill (configurable window) and then switches to your chosen schedule. You'll see sync runs appear in the **Sync History** tab within a few minutes.
  </Step>
</Steps>

## Connect via the API

### 1. Look up the connector type

```bash theme={null}
curl https://api.causeloop.ai/v1/connector-catalog/jira \
  -H "Authorization: Bearer $TOKEN"
```

Note the `type` and `oauth` fields in the response — they determine your next step.

### 2. Create the connector record

```bash theme={null}
curl -X POST https://api.causeloop.ai/v1/connectors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "jira",
    "display_name": "Production Jira",
    "credentials": {}
  }'
```

The response includes the connector `id` (e.g. `con_01hx4k2m9p`). Save it — you'll need it for the next step.

### 3a. OAuth connectors — start the authorization flow

```bash theme={null}
curl -X POST https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/oauth/start \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "authorize_url": "https://auth.atlassian.com/authorize?...",
  "state": "oast_01hx5c3d4e",
  "expires_at": "2026-06-14T10:10:00Z"
}
```

Redirect the user's browser to `authorize_url`. The state token expires in **10 minutes** — the user must complete authorization within that window.

### 3b. Handle the OAuth callback

After the user grants access, the provider redirects to:

```
https://api.causeloop.ai/v1/connectors/oauth/callback?code=AUTH_CODE&state=oast_01hx5c3d4e
```

Causeloop handles the callback automatically — it exchanges the authorization code for tokens, stores them encrypted, and marks the connector `connected`. You don't need to call this endpoint yourself.

<Note>
  When building your own OAuth UX, configure your provider app's **Redirect URI** to `https://api.causeloop.ai/v1/connectors/oauth/callback`. This is the only URI the callback endpoint accepts.
</Note>

### 3c. API key connectors — supply credentials directly

```bash theme={null}
curl -X PATCH https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "api_key": "your-api-key-here"
    }
  }'
```

### 4. Test the connection

```bash theme={null}
curl -X POST https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/test \
  -H "Authorization: Bearer $TOKEN"
```

A `200` response with `"success": true` confirms the connector can reach the provider. The response also includes `latency_ms` — a real, measured round-trip time for the test call, not an estimate.

### 5. Trigger a sync

```bash theme={null}
curl -X POST https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/sync \
  -H "Authorization: Bearer $TOKEN"
```

Returns `202 Accepted` with a `sync_run_id`. Poll `GET /v1/connectors/{id}/sync-runs/{run_id}` to track progress.

## OAuth flow in detail

For OAuth connectors, Causeloop implements a standard 3-leg authorization code flow:

```
Your app / UI                  Causeloop                     Provider
     │                            │                              │
     │  POST /oauth/start         │                              │
     │ ──────────────────────────►│                              │
     │  {authorize_url, state}    │                              │
     │ ◄──────────────────────────│                              │
     │                            │                              │
     │  Redirect user to          │                              │
     │  authorize_url ────────────────────────────────────────► │
     │                            │                              │
     │                            │  ?code=XXX&state=YYY         │
     │                            │ ◄────────────────────────────│
     │  (callback handled by Causeloop)                          │
     │                            │  exchange code for tokens    │
     │                            │ ─────────────────────────── ►│
     │                            │  {access_token, refresh_token}│
     │                            │ ◄────────────────────────────│
     │                            │  connector status → connected │
     │ ◄──────────────────────────│                              │
```

Tokens are stored encrypted. Causeloop refreshes the access token automatically before each sync — you never need to handle token refresh.

## Managing schedule and backfill

### Set a custom sync schedule

```bash theme={null}
curl -X PUT https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/schedule \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cron": "0 */2 * * *",
    "timezone": "America/New_York"
  }'
```

### Run a historical backfill

```bash theme={null}
curl -X POST https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/backfill \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-01-01T00:00:00Z",
    "to": "2026-06-01T00:00:00Z"
  }'
```

## Connector status reference

| Status          | Meaning                                                       |
| --------------- | ------------------------------------------------------------- |
| `pending`       | Created but not yet authorized or tested                      |
| `connected`     | Active and syncing normally                                   |
| `paused`        | Manually paused — syncs will not run                          |
| `error`         | Last sync failed — check sync history for details             |
| `oauth_expired` | OAuth token expired and could not be refreshed — re-authorize |

<Tip>
  Subscribe to `connector.sync.failed` events via an [outbound webhook](/integrations/webhooks) to get notified immediately when a connector goes into an error state.
</Tip>