Skip to main content
A Provider usually accepts more than one kind of credential: a personal API key, an OAuth app, or a service account. A Provider Plugin describes each kind as an authentication strategy. When you connect a Provider, you choose one strategy and send the fields that its configSchema describes. The Provider connection stores the strategy that you chose (authenticationStrategy). It also stores a copy of your configuration in which every secret field is empty.

How a strategy is described

A leaf connection method lists the strategies that you can use in supportedAuthStrategies. Each strategy has these fields: Read one connection to get the full definition of each strategy of its plugin, in connector.supportedAuthStrategies. The full definition also has these fields: Non-secret fields, such as a client ID, come back on the connection. Secret fields, such as API keys, client secrets, and refresh tokens, come back as empty strings. Keep your own copy of a secret if you need it elsewhere.

Authentication types

type is one of these values: The Provider directory lists only the strategies that Parable can sync with. Parable refuses a connection that names any other strategy. A plugin often offers more than one strategy. Linear, for example, offers a personal API key and OAuth 2.0 strategies. You choose one strategy for each connection. A plugin with sensitive Taps offers a second strategy that adds their access.

Ingestion settings

Some plugins also need ingestion settings, such as a GitHub organization (orgId) or the Google Workspace admin user that a service account acts as. The connection method’s ingestionConfigSchema describes them. A strategy’s own ingestionConfigSchema replaces it. Send the values as ingestionConfig. These values fill URL and path templates. They do not change how Parable pages through the Provider. See How a sync reads a Provider. Do not put a credential in ingestionConfig. A sync refuses an ingestion setting that holds a credential field.

Connect a Provider

POST /api/connectors takes an encrypted request body, because it carries your credentials. A plain JSON body fails with 400 Encrypted payload is required. The SDKs encrypt the body when you give them your Workspace’s public key. Encrypted requests explains the key and the envelope. This example connects GitHub for the organization acme-corp with a personal access token.
  1. List the connection methods of the Provider:
  2. Choose a leaf method (isLeaf: true). Record its id and its connectorId.
  3. Choose one strategy from its supportedAuthStrategies. Record the strategy id.
  4. Build authenticationConfig from the strategy’s configSchema.
  5. Build ingestionConfig from the ingestion settings schema.
  6. Get your Workspace’s public key, and create the connection. With the TypeScript SDK (see TypeScript to create sdk):
    Without the SDK, get the key from GET /api/security/encryption-key, with the X-Tenant header. Encrypt the JSON input above, and send the envelope as the request body:
  7. Record id in the response. It is the ID of the new Provider connection. The response also has credentialMetadataId.
  8. Read the connection. Check credentialStatus and connectionStatus:
idempotencyKey is optional. When you send the same key again, Parable returns the connection that the first request created, and changes nothing. Use it to retry a request safely.

What happens after you connect

A saved connection is not yet a validated connection. Parable checks the credentials against the Provider and records the result as the connection’s credentialStatus.
  • When the credentials are valid, Parable starts the first sync and a daily schedule. The first sync reads the 90 whole UTC days before the day of the check. The first scheduled sync runs 24 hours after the check and reads the day of the check. Each scheduled sync reads one UTC day.
  • When the check of a save fails, no sync starts. A later valid save or check starts the first sync and the schedule.
  • When the plugin’s availability is authorized, Parable saves and checks the credentials, but no sync starts. See Availability.
  • A Provider that sends data to Parable never gets a first sync or a schedule. Its senders deliver the data. See Providers that send data.
  • When the first sync fails or is canceled, the next valid credential save starts a new one. A check does not. While a first sync waits, runs, or has finished, a new save or check starts no second one.
An oauth2_refresh connection whose strategy declares an authorizeUrl has no token until a person completes the Provider’s consent screen. Parable does not check the save before consent, and no sync starts. Completing consent counts as a credential save, so the rules above apply to it. A new consent starts no second first sync unless the first one failed or was canceled. See Strategies that use a consent screen. An oauth2_refresh strategy with no authorizeUrl has no consent screen. The Provider issues the refresh token in its own admin, such as Workday’s Manage Refresh Tokens for Integrations. The save carries that refresh token with the other fields, and Parable checks it like any other credential save. An oauth2_refresh strategy that declares an authorizeUrl sends a person to the Provider’s consent screen. You can run that flow from code:
  1. Create the connection with the OAuth strategy, as above. Its configSchema says which fields you send before consent, such as the client ID and client secret of your own OAuth app. Parable stores the tokens after consent.
  2. Start the consent:
    The response has authorizeUrl. It carries a PKCE code_challenge (S256), and Parable sends the matching code_verifier when it exchanges the code. When Parable owns the OAuth app, Parable ignores clientId and clientSecret. When you authorize again, an empty clientSecret reuses the stored one.
  3. Open authorizeUrl in a browser where the same person is signed in to the Workspace app, within 10 minutes. The person approves access on the Provider’s screen.
  4. The Provider sends the browser to the callback URL. The Workspace app then calls POST /api/connectors/connector-oauth-complete with the state and the code. Parable stores the tokens and checks them. Valid tokens start the 90-day first sync and the daily schedule, by the rules in What happens after you connect.
  5. Read the connection and check credentialStatus.
redirectUri must be the callback path, /platform/providers/oauth/callback, on a Parable address. Use your Workspace’s address. Parable refuses a URL on another host or path. When Parable owns the OAuth app, Parable sends its own apex callback to the Provider instead, and the callback page returns the browser to your Workspace. The consent belongs to the person who started it, and it expires after 10 minutes.

Who owns the OAuth app

In Parable’s hosted GCP environments, Parable reads the client of an app it owns by connector slug. Adding one needs no code change: see Set a Parable-owned OAuth client. Your own OAuth app lists the redirect URI https://<workspace>.parable.work/platform/providers/oauth/callback, with your Workspace slug in place of <workspace>.

Change a connection

POST /api/connectors/configure changes the strategy, the credentials, the ingestion settings, or the parent filters of an existing connection. It takes an encrypted request body, like the create call. Send only what changes:
The response has success, credentialMetadataId, and message. success is true when Parable stored the change, even when the new credentials fail their check. Read credentialStatus on the connection afterward. New credentials start the same first sync as a new connection, under the same rules. A change of ingestion settings alone starts no sync. Parable refuses a change of ingestion settings while the plugin’s availability is authorized. This call and the two consent calls need permission to manage the connection’s credentials.
  • To remove a connection, send DELETE /api/connectors/{tenantConnectorId}. The connection stops bringing data in.
  • To read every settings change on a connection, send GET /api/connectors/{tenantConnectorId}/config-history. Each record holds the configuration with its secret fields empty.

Check credentials

To test the stored credentials of a connection against the Provider, send its credentialMetadataId:
This call does not take new credentials. It checks the stored ones and records the result as the connection’s credentialStatus. The response has success, status, message, errorCode, and validatedAt. A valid check can also start syncs:
  • It starts the daily schedule when the connection has none, or resumes a paused one.
  • It starts the 90-day first sync when the connection never had one, for example because the check at save time failed.
A check starts neither when the plugin’s availability is authorized, or for a Provider that sends data. A check never replaces a first sync, even one that failed or was canceled. To start a new first sync, save the credentials again with POST /api/connectors/configure. For an oauth2_refresh connection, complete consent again. errorCode is one of auth_failed, insufficient_permissions, expired, config_invalid, or internal_error. The connection keeps the last one in credentialErrorCode, which is null after a valid check. config_invalid means that the settings, not the credential, are wrong, for example a host field that Parable cannot use. Some such checks keep the connection’s stored credentialStatus and only report the code. Others mark the credential invalid, and the connection’s status becomes config_invalid. A valid check can write back non-secret values that the Provider reports. Parable adds them to the connection’s ingestionConfig. Tableau, for example, writes back the site ID of the site that the credentials sign in to. When a check fails, read why: Each call returns an errorCode and an errorMessage. Neither call returns a secret.
The Provider Plugin guides explain how to create an OAuth app, generate a key, and grant scopes for each Provider.