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 insupportedAuthStrategies. 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.
-
List the connection methods of the Provider:
-
Choose a leaf method (
isLeaf: true). Record itsidand itsconnectorId. -
Choose one strategy from its
supportedAuthStrategies. Record the strategyid. -
Build
authenticationConfigfrom the strategy’sconfigSchema. -
Build
ingestionConfigfrom the ingestion settings schema. -
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 fromGET /api/security/encryption-key, with theX-Tenantheader. Encrypt the JSON input above, and send the envelope as the request body: -
Record
idin the response. It is the ID of the new Provider connection. The response also hascredentialMetadataId. -
Read the connection. Check
credentialStatusandconnectionStatus:
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’scredentialStatus.
- 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.
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.
Strategies that use a consent screen
Anoauth2_refresh strategy that declares an authorizeUrl sends a person to
the Provider’s consent screen. You can run that flow from code:
-
Create the connection with the OAuth strategy, as above. Its
configSchemasays 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. -
Start the consent:
The response has
authorizeUrl. It carries a PKCEcode_challenge(S256), and Parable sends the matchingcode_verifierwhen it exchanges the code. When Parable owns the OAuth app, Parable ignoresclientIdandclientSecret. When you authorize again, an emptyclientSecretreuses the stored one. -
Open
authorizeUrlin 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. -
The Provider sends the browser to the callback URL. The Workspace app then
calls
POST /api/connectors/connector-oauth-completewith thestateand thecode. 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. -
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:
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 itscredentialMetadataId:
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.
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.