Connectors and OAuth

Apps reach outside systems in three ways: through OAuth connections the platform brokers, through data source connectors that follow a customer's own storage, and directly from their own code with their own secrets. This chapter covers the first two, which the platform holds credentials for, and where the third fits.

#OAuth Connections

The platform holds OAuth client registrations for a set of providers: Google, Slack, HubSpot, LinkedIn, Notion, Airtable, Calendly, Typeform, QuickBooks, Canva, TikTok, and X. A workspace member connects an account through the standard authorization-code flow, with PKCE where the provider supports it, and the platform stores the resulting tokens encrypted and refreshes them as they expire.

Each provider is one module implementing a common interface: build the authorization URL, exchange the code, refresh the token, and describe the account. The redirect URI is built on the product's own host and is identical at authorize and exchange. The operator's client id and secret for each provider are declared in the counterparty registry as an OAuth-app surface and obtained only through it; a workspace that must use its own OAuth app for a provider can register one.

A connected account is a resource of the workspace, scoped to the apps that are allowed to use it. When a method uses a connection, the platform resolves the current token and makes the call, so the app code never sees the token and a revoked connection stops working everywhere at once.

#Data Source Connectors

A data source can follow a bucket the customer owns. A connector records where to list, which of the app's secrets hold the access keys, and what to do about deletions. Beside it, an object index records each customer key, the ETag it was ingested at, the document it became, and the last sync that saw it, so a sync is a diff rather than a re-read.

Connectors work against any S3-compatible endpoint. A sync lists the bucket under the configured prefix and plans the adds, changes, and removals. It auto-approves under a ceiling, asks otherwise, and then runs the ingest through the same pipeline as an uploaded document. Deletion policy is per connector: a key that disappears upstream can take its document with it, or leave it in place.

The credentials for a connector are the app's own secrets, referenced by name and decrypted only when a sync runs. See Secrets and Retrieval.

#Direct Integrations

An app can call any third party directly from its methods, with its own keys held as app secrets and injected into its sandbox. That traffic leaves the sandbox for the public internet under the network policy described in The Trust Boundary. It is the app's own integration: the platform does not see it, meter it, or hold its credential.

The line between the three is where the credential lives. Platform-brokered connections and platform actions run through the counterparty registry with the platform's or the workspace's key, are metered, and appear in the subprocessor list. App-held secrets are the app's, and the platform's role is to keep them encrypted and deliver them into the right VM.