@pabbly/connect-platform

Node SDK for the Pabbly Connect Platform API — use Connect as your product's connection manager: let your customers connect 1,000+ apps through hosted OAuth/credential flows, and vend always-fresh access tokens from your backend.

Backend-only. The tenant key and vended tokens must never reach a browser, mobile app, or LLM context. Requires Node ≥ 18.

npm install @pabbly/connect-platform

const { PabblyConnectPlatform, NeedsReconnectionError } = require('@pabbly/connect-platform');
const pc = new PabblyConnectPlatform({ apiKey: process.env.PC_TENANT_KEY });

const customer = '[email protected]';                 // REQUIRED on every connection call

const { apps } = await pc.listApps({ search: 'gmail' });
const link = await pc.createRequestLink(customer, { appId: apps[0].id, name: 'Work Gmail' });
// → open link.request_link in a popup (browser helper); poll until active:
const conn = await pc.waitForConnection(customer, link.connection_id);

if (conn.status === 'active') {
  const token = await pc.getToken(customer, link.connection_id);   // { access_token, … } or { fields, … }
}

API

| Method | Notes | |---|---| | new PabblyConnectPlatform({ apiKey, baseUrl?, maxRetries=2, timeoutMs=30000 }) | apiKey = pk_live_… | | listApps({ search?, page?, limit? }) | catalog; no email | | getApp(appId) | | | createRequestLink(email, { appId, name }) | → { connection_id, request_token, request_link, expires_at, app } | | getConnection(email, id) | status: pending/active/rejected/expired | | waitForConnection(email, id, { intervalMs?, timeoutMs? }) | resolves when status leaves pending | | getToken(email, id) | OAuth → { access_token, token_type, expires_in, auth_type }; else { auth_type, fields }. Never persist/log. | | listConnections(email, { appId?, page?, limit? }) | only connections your tenant created | | deleteConnection(email, id) | needs delete capability |

email is required on every connection method — each call acts on a specific customer, sourced from your authenticated session. Omitting it throws.

Errors

Typed subclasses of PabblyConnectError carry .status, .code, .response: NeedsReconnectionError (401 — re-run the connect flow), ConnectionDeletedError (404), CapabilityDisabledError (403), RateLimitedError (429, .retryAfter), UpstreamUnavailableError (503; auto-retried twice).

Full guide

See docs/platform-api-integration-guide.md in the backend repo for the end-to-end flow, REST equivalents, the security model, and the production checklist.