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

# How Provider connections work

> A Provider connection joins a Provider Plugin to your Workspace: authentication strategies, Taps, and rate limits.

A **Provider** is a system that your company uses, such as GitHub, Jira,
Slack, Linear, or Workday. A **Provider connection** brings the data of one
Provider into your Workspace. Parable syncs that data into the
[Provider Pool](https://developers.askparable.com/data/providers.md), where you query it with SQL.

> [!NOTE]
>
> Parable reads data from your Providers. It does not write to your systems.

## The model

Every Provider connection has two parts. Parable ships a **Provider Plugin**,
and your Workspace configures a **Provider connection** from it.

```mermaid theme={null}
flowchart TD
  P["Provider in the directory"] --> D["Provider Plugin"]
  D --> A["Authentication strategies"]
  D --> T["Taps"]
  D --> G["Traversal"]
  D --> R["Rate limits"]
  A --> C["Your Provider connection"]
  T --> C
  C --> L["Tables in the Provider Pool"]
```

| Part | What it is | Name in the API |
| - | - | - |
| Provider | The system in the Provider directory, such as GitHub, Linear, or Google Workspace. | `vendor` |
| Connection method | One way to connect to a Provider, such as Jira Cloud with an API token. A leaf method names the Provider Plugin that it uses. | `grouping` |
| Provider Plugin | How Parable talks to the Provider: authentication strategies, Taps, traversal, rate limits, and base URL. | `connector` |
| Authentication strategy | One way to authenticate. A plugin can offer several. You choose one when you connect. See [Authentication](https://developers.askparable.com/connectors/auth.md). | `supportedAuthStrategies[]` |
| Tap | One stream of records, such as `issues`, `pull_requests`, or `channels`. See [Taps](https://developers.askparable.com/connectors/taps.md). | `tap` |
| Traversal | The graph that tells a sync which Taps run first and which Taps run once for each parent record. See [How a sync reads a Provider](https://developers.askparable.com/connectors/ingestion.md). | `traversal` |
| Provider connection | Your configured copy: the strategy you chose, credentials, ingestion settings, Taps, and sync status. | `tenantConnector`, `TenantConnectorInstance` |

The Provider Plugin is the same for every Workspace. The Provider connection
belongs to your Workspace.

Examples on these pages use three variables. `$PARABLE_API_URL` is the base
URL of the Workspace API. `$PARABLE_API_TOKEN` is your token.
`$PARABLE_WORKSPACE` is your Workspace slug, such as `acme-corp`.

## Browse the Provider directory

The directory needs no sign-in. Search it for a Provider:

```bash theme={null}
curl "$PARABLE_API_URL/api/vendors/parable-vendors?search=linear"
```

List the connection methods of one Provider. A leaf method (`isLeaf: true`)
carries the `connectorId`, the authentication strategies that you can use, and
the `ingestionConfigSchema`:

```bash theme={null}
curl "$PARABLE_API_URL/api/vendors/parable-vendor-groupings/linear"
```

### Browse by function

The directory also lists one entry for each Provider product, with no setup
details:

```bash theme={null}
curl "$PARABLE_API_URL/api/vendors/provider-directory" \
  -H "X-Tenant: $PARABLE_WORKSPACE"
```

Each entry has `connectorId`, `name`, `description`, `logo`, `releaseStage`,
and `groupingIds`, the connection methods of the product. `variants` describes
each of those connection methods with its own `connectorId`, `name`,
`description`, `logo`, `releaseStage` and `groupingPath`. When you send
`X-Tenant`, `priority` says whether your Workspace marks the Provider
`required` or `suggested`, on the entry and on each variant.

Categories group Providers by business function, such as engineering or
finance:

```bash theme={null}
curl "$PARABLE_API_URL/api/connectors/categories" \
  -H "Authorization: Bearer $PARABLE_API_TOKEN" \
  -H "X-Tenant: $PARABLE_WORKSPACE"
```

Each category has `slug`, `label`, `sortOrder`, `parent`, and `connectorIds`.
The list is flat. Build the tree from `parent.id`, and match `connectorIds` to
the `connectorId` of each directory entry. A category with `isLegacy: true`
stays in the list for earlier selections.

### Availability

Each leaf method says how far Parable has released its plugin:

| Field | Values | Meaning |
| - | - | - |
| `releaseStage` | `ga`, `early_access`, `invite_access`, `coming_soon` | How the Provider is offered. A `coming_soon` Provider shows in the directory, and `connectorReleaseStatus` decides whether you can connect it. Only Workspaces that Parable admits see an `invite_access` Provider. Ask your Parable representative for access. |
| `connectorReleaseStatus` | `draft`, `configured`, `authorized`, `executable`, `landing`, `materialized`, `verified`, `deprecated` | What the plugin can do now. |

`connectorReleaseStatus` decides what your Workspace can do:

* **Before `authorized`.** Parable refuses a connection or a credential save
  (`WA-CN-005`).
* **`authorized`.** You can create the connection, save credentials, and
  check them. No sync starts, and Parable refuses a change of ingestion
  settings. When the plugin reaches `executable`, save the credentials again
  or [check them](https://developers.askparable.com/connectors/auth.md#check-credentials) to start the first
  sync.
* **`executable` and later.** A valid credential save starts the first sync.
* **`deprecated`.** Parable refuses a new connection or a credential save
  (`WA-CN-006`).

A Provider that Parable has not released to your Workspace answers like a
Provider that does not exist.

### Providers that send data

Most plugins read the Provider on a schedule. Some Providers send their data
to Parable instead, such as webhooks and telemetry exporters. A leaf method
of such a Provider has `integrationClass: streaming`, a `protocolType` such as
`webhook` or `otlp`, and `supportedInboundAuthStrategies`, the ways that
Parable can verify its senders. See [Providers that send data](https://developers.askparable.com/connectors/push.md).

## Read your connections

List the Provider connections in your Workspace:

```bash theme={null}
curl "$PARABLE_API_URL/api/vendors/tenant-connector-instances" \
  -H "Authorization: Bearer $PARABLE_API_TOKEN" \
  -H "X-Tenant: $PARABLE_WORKSPACE"
```

Each item has the nested Provider Plugin in `connector`. In this list,
`connector.taps` is empty. Add `?includeTaps=true` to get every Tap with its
schema. That makes the response much larger. To read the full plugin of one
connection, read that connection:

```bash theme={null}
curl "$PARABLE_API_URL/api/vendors/tenant-connector-instances/$CONNECTION_ID" \
  -H "Authorization: Bearer $PARABLE_API_TOKEN" \
  -H "X-Tenant: $PARABLE_WORKSPACE"
```

To check only whether the data of each connection is current, list the
connection freshness. It has no Provider Plugin, so the response stays small:

```bash theme={null}
curl "$PARABLE_API_URL/api/vendors/tenant-connector-freshness" \
  -H "Authorization: Bearer $PARABLE_API_TOKEN" \
  -H "X-Tenant: $PARABLE_WORKSPACE"
```

* Each item has the connection's `connectionStatus`,
  `connectionStatusMessage`, `lastSyncAt`, and `lastSyncStatus`, the same
  values as in the full list. A Provider that sends data also has
  `lastDataReceivedAt`.
* A page holds at most `limit` connections, newest first: 50 by default, 100
  at most. It stops before 40,000 characters, but it always holds one
  connection.
* Send `nextOffset` back as `offset` for the next page. The last page has no
  `nextOffset`.

## What your Workspace controls

* **Which Providers are connected**, with which strategy and credentials.
  The API never returns a secret value. A secret field comes back as an empty
  string.
* **Which Taps run.** A new connection starts with the plugin's default Taps.
  Other Taps are opt-in. See [Taps](https://developers.askparable.com/connectors/taps.md#turn-taps-on-and-off).
* **Sync health.** Each connection reports these fields:

| Field | Meaning |
| - | - |
| `connectionStatus`, `connectionStatusMessage` | The state of the connection and a sentence that explains it. |
| `credentialStatus`, `hasValidCredentials` | The result of the last credential check: `valid`, `invalid`, `expired`, `pending`, or `unvalidated`. |
| `credentialErrorCode` | Why the last check failed: `auth_failed`, `insufficient_permissions`, `expired`, `config_invalid`, or `internal_error`. Null after a valid check. See [Check credentials](https://developers.askparable.com/connectors/auth.md#check-credentials). |
| `lastSyncAt`, `lastSyncStatus` | When the last sync ran, and how it ended. |
| `lastDataReceivedAt` | For a Provider that sends data: when a sender last delivered data. Null until the first delivery, and always null for a Provider that Parable reads. See [Providers that send data](https://developers.askparable.com/connectors/push.md). |

You do not choose pagination or sync mode. The Provider Plugin sets them for
each Tap, so that Parable reads the Provider correctly. You can read them, but
you cannot change them.
[How a sync reads a Provider](https://developers.askparable.com/connectors/ingestion.md) explains each field.

## Rate limits

Each Provider Plugin limits how fast Parable calls the Provider. A plugin
sets one of two kinds of limit:

* **A fixed limit.** It sets requests per second, concurrent requests, and
  retry rules.
* **A Provider budget.** It follows the quota that the Provider publishes and
  the rate-limit headers that it returns.

A Tap can set its own limit. You cannot change these limits. They explain why
a large first sync takes time.

## Request a Provider

If the directory does not list a system that you use, request it:

```bash theme={null}
curl -X POST "$PARABLE_API_URL/api/connector-requests/connector-requests" \
  -H "Authorization: Bearer $PARABLE_API_TOKEN" \
  -H "X-Tenant: $PARABLE_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorName": "Acme Ticketing",
    "notes": "We need tickets and their comments."
  }'
```

A request does not create a Provider connection. Read your requests and their
`status` with `GET /api/connector-requests/connector-requests`. You can also
request a Provider from **Providers** in the Workspace app.

> [!NOTE]
>
> Setup guides for each Provider (OAuth apps, API keys, and scopes) are in the
> [Provider Plugin guides](https://docs.parable.work/plugins/provider-plugins).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.