Connectors and OAuth
The three ways an app reaches outside systems: brokered OAuth connections, data source connectors that follow a customer's own storage, and direct integrations with the app's own secrets, drawn by where the credential lives.
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
A workspace member connects an account at a third-party provider. Google, Slack, HubSpot, LinkedIn, Notion, Airtable, Calendly, Typeform, QuickBooks, and X connect through the platform's own OAuth client registrations. Canva connects through an OAuth app the workspace registers itself, since the platform holds none for it. Connecting is the standard authorization-code flow, with PKCE for Airtable, Calendly, and Canva.
The redeem step is accepted only for the state value that the same person's flow started, so a link carrying someone else's code cannot connect their account into another workspace. The platform stores the resulting tokens encrypted with KMS and refreshes them when they are used near expiry. LinkedIn issues no refresh token, so a LinkedIn connection is reconnected when it lapses. The same store holds saved API keys and external database credentials, also encrypted.
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's own OAuth app, where a provider needs one or where Slack is set to use one, is an admin's to register.
A connection belongs to the workspace and is either private to the person who connected it or shared with the whole workspace. Slack connections are shared when made. There is no per-app grant: a shared connection is usable by every app in the workspace, and a Remy app that names no connection falls back only to a shared one, never to someone's private account. Members connect accounts and change the connections they made, and admins can also unshare or remove shared ones. 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, plans the adds, changes, and removals, auto-approves under a ceiling and asks otherwise, and 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 Network Topology and Trust Boundaries. 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.