Skip to main content
A Provider connection combines a Provider Plugin with the choices owned by one Workspace: its authentication strategy, credentials, connection-specific configuration, enabled data streams, and sync state. The plugin definition is shared across Workspaces. The connection is not.
The reconfigure and OAuth operations have no public reference page on this site. The developer site describes how to connect a Provider through the API, in Authentication strategies. You can also connect a Provider from Providers in the Workspace app.

​
Create a connection

Choose a Provider Plugin and grouping from the Provider Directory, then create the Workspace connection:
Build authenticationConfig from the selected strategy’s configSchema. Build ingestionConfig from the plugin’s ingestionConfigSchema when one is present. The latter supplies connection-specific values such as an organization identifier or instance host; it does not redefine the plugin’s traversal or pagination behavior. In the Workspace app, the connector page creates the connection. Its empty row reads Testing from the moment you select Save & test connection. When the save lands, the new connection’s row takes the place of the empty row, stays open, and shows credential validation progress. A saved connection has not necessarily passed validation. A connection whose test fails stays saved, and its row shows the error.

​
The connector page

Each Provider Plugin grouping has one page under Providers. A row of two tabs at its top holds the page. The second tab is Connect until the Workspace has a connection for the plugin, and Manage after that: On Learn, the first accordion, normally Overview, starts open, and the others start closed. When the docs have no section for Learn, it shows only “Documentation is not available yet.” The accordions of Connect and Manage start closed. Each of them shows when the docs of any auth method have its section. When no form can be used, in a catalog preview, on the global catalog, or for a reader who may not add a connection, Connect opens its first accordion. In the accordions of every tab, the docs’ headings draw no larger than the accordion’s title. A section’s highest heading draws as h4, at the title’s 14px, and the headings below it keep their order under it, down to h6. Headings in code blocks do not change. Above every tab, a Coming Soon connector shows its In development notice. Above Learn and Connect, a plugin with more than one auth method shows the method choice, and the docs show that method’s sections. On Connect, the empty row uses that choice and shows no choice of its own. A change of method, made in either choice, clears what the empty row’s form holds. On Learn, an open accordion stays open when the new method’s docs have its section. When the new method’s docs have none of the open sections, their first section opens. On Connect and Manage, a method whose docs lack a section shows “Documentation is not available yet.” in that accordion, so a change of method never takes one of their accordions away. Manage has no method choice above it, because each form in it has its own. Its accordions start on the method of the connection that ?connectorId= names, or of the only connection. Otherwise they start on the default method: the method that the grouping’s address names, such as OAuth for Gong’s oauth grouping, else the plugin’s first method. A method that the empty row’s form chooses then takes over. The page has no header of its own: the trail above it names the connector, with its logo, and the band shows its description. Outside the Providers frame no band shows, so the page draws the connector’s name and description under its own trail. The tab row starts with the way back to a Parable, when a Parable’s Connect opened the page, and ends with the connector’s release stage, such as Coming Soon. Generally Available and, for now, Early Access show no badge there. The tab row and the tab in view share one centered column, at most 896px wide, as on Protection > AI Processors. The tab row’s rule and the scroll bar stay at the full width of the page. The page opens on Manage when the Workspace has a connection for the plugin, and on Learn otherwise. A connector that takes no credentials yet shows its catalog preview unless the Workspace has a connection for it: Learn, and Connect with the accordions alone. The preview shows Connect only when its docs have a setup guide or troubleshooting. The preview’s tab follows the address, as the page’s does. The page has no back link. The browser’s back button and the breadcrumbs go back. Manage lists the connections, newest first, one row for each. A row’s header is the card that the Provider’s page shows for the connection, with its leads on both sides. One row is open at a time. Opening a row does not change its header: only its chevron turns down. The connection’s form opens in a plain card under the header, with no status color. When the Workspace has exactly one connection, its row opens. A closed row reads the same as the Provider page’s card for that connection: the status ring, the name, the status sentence, the status badge, and the release stage badge, such as Beta. Both read the stored connection. While a sync runs, they show the status from before the sync. The status badge follows the same rules in both places: An open row keeps its status sentence under its name. The status notice in the form reads the same status as the row’s header, so it can repeat that sentence, and while a sync runs it also shows the status from before the sync. Under its header, an open row holds the connection’s form, its OAuth authorization, the ingest endpoint of a push connection, and its Provider Pool rebuilds. Add connection, beside the connection count in Manage, opens an empty row above the other connections. Before the first connection, Connect shows that empty row, open. When the last connection goes, for example because another reader removed it, the second tab becomes Connect again. The reader stays on it, and the empty row opens. The empty row has the same header as a saved row: an empty ring, the name you type, and a Not connected badge, which reads Testing from the click on Save & test connection. When the save lands, the new connection’s row takes its place. The page’s address is its grouping’s own address, /platform/providers/<vendor>/<grouping path>. The address follows the view, and the page replaces it without a new history entry:
  • The address alone shows the default tab: Manage when the Workspace has a connection, else Learn.
  • ?tab=learn shows Learn. ?tab=connect and ?tab=manage both show the second tab, whichever name it has now, and the page writes that name. The default tab writes no tab.
  • ?tab=troubleshoot, from when Troubleshoot was a tab, shows the second tab with Troubleshooting open.
  • ?connectorId=<id> shows Manage with that row open. When the page first loads at this address and the row’s header is out of sight, the row scrolls into view once.
  • ?add=1 asks to add a connection. With a connection in place, Manage opens with the empty row open above the others. Before the first connection, Connect opens with the empty row. The page drops add on its first write.
The older addresses keep their meaning, and the page then moves to its own address:
  • <grouping path>/create asks to add a connection, as ?add=1 does: with a connection in place, Manage opens with the empty row open, else Connect. A link that sets up a connection, and a bookmark, still land on the form.
  • <grouping path>/connection shows the second tab: Manage, or Connect before the first connection.
  • <grouping path>/connection?connectorId=<id> shows Manage with that row open. Emails link to a connection this way.
A save that adds a connection, and the OAuth callback, return to that connection’s row: ?connectorId=<id>, with a one-time created=1 or oauthComplete=1 that the page drops. connectorId wins over add. While a save runs, the page holds its address writes, since a write is a move of its own and would cancel the save. A reload or a copied link opens the same view. The browser’s back button leaves the page. Save stays off until the page has hydrated, because the form writes its hidden fields on the client. Every form on the page posts to the address it shows, whichever form that address takes, and reaches the connector’s actions. An update post that names no connection is refused with 400, or with 403 for a reader who may not change connections. One exception: a post to <grouping path>/create that names no connection adds one, because the form of that page posted so before the connector page replaced it. A card on the Providers overview, and a connector’s row in the Providers panel, link to the connector page:
  • No connection: the page’s own address, which opens Learn.
  • One connection: its row, open.
  • Several connections, some of which need attention: the row of the most urgent of those, open, in the order that the overview sorts its cards by. For a Workspace reader, a connection the Workspace must fix comes before one that Parable must fix. For a Parable administrator, a failed connection comes before one with a warning.
  • Several connections, none of which needs attention: Manage, with no row open.
Each card on the overview is one connector, so a product with several variants, such as Jira Cloud and Jira Data Center, has a card for each, and each card links to its own connector page. New connection on a Provider’s card links to ?add=1. A Parable’s Connect does the same for a Provider the Workspace has not connected, and opens its connection’s row otherwise.

​
Check the stored credentials again

When the stored credentials are unvalidated or invalid, the status notice in the connection’s row offers Check again, whatever the notice says about the connection. An unvalidated credential is eligible to sync, so a sync can run while no check has judged the credential. The notice then shows the status from before the sync, as the row’s header does. Check again runs POST /api/connectors/validate on the credentials already stored for the connection, so a change on Parable’s side can change the verdict without re-entering secrets. Check again needs permission to configure connectors. It shows the verdict with its message, then refreshes the connection status. When the check passes on a pull connection, Parable makes sure the daily schedule exists. If the connection never had a backfill, for example because its first check failed, Parable also starts the 90-day first sync. When the strategy authorizes through the Provider’s OAuth consent screen, the connection’s row sends the user there. After Parable exchanges the authorization code, the user returns to the connector page with that row open, and the row shows validation progress.

​
Read connection state

The instance reports computed fields such as connection status, credential validity, and recent sync state. Use the Provider Directory instance operations to list all connections or fetch one by ID.

​
Reconfigure or remove a connection

  • POST /api/connectors/configure replaces connection configuration or credentials using a supported authentication strategy.
  • DELETE /api/connectors/{tenantConnectorId} removes the Workspace’s connection.
  • The configuration-history operation shows prior configuration attempts without returning secret values.

​
Who can create or change a connection

The Workspace app offers a control only when your role allows the operation behind it: A permission covers its children. tenant.connectors and the Workspace Administrator’s tenant cover both Workspace permissions. tenant.connectors.edit alone does not allow saving a connection. A user who can view connections but cannot change them sees each connection’s row read-only, with a View only notice. A user who cannot create a connection sees the first connection’s box in Connect read-only, and no Add connection in Manage. See Provider authentication for credential handling and data streams for per-stream controls.