Connecting a Source

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

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.

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.

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.

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.

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.

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.

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.

Connect via the API

1. Look up the connector type

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

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

curl -X POST https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/oauth/start \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "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.

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.

3c. API key connectors — supply credentials directly

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

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

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

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

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

Subscribe to connector.sync.failed events via an outbound webhook to get notified immediately when a connector goes into an error state.

​Connect via the UI

​Connect via the API

​1. Look up the connector type

​2. Create the connector record

​3a. OAuth connectors — start the authorization flow

​3b. Handle the OAuth callback

​3c. API key connectors — supply credentials directly

​4. Test the connection

​5. Trigger a sync

​OAuth flow in detail

​Managing schedule and backfill

​Set a custom sync schedule

​Run a historical backfill

​Connector status reference

Connect via the UI

Connect via the API

1. Look up the connector type

2. Create the connector record

3a. OAuth connectors — start the authorization flow

3b. Handle the OAuth callback

3c. API key connectors — supply credentials directly

4. Test the connection

5. Trigger a sync

OAuth flow in detail

Managing schedule and backfill

Set a custom sync schedule

Run a historical backfill

Connector status reference