Integrations catalog

Appbricx ships a registry of ~200 pre-wired connectors — Slack, Gmail, Stripe, Discord, Notion, GitHub, Shopify, HubSpot, and dozens more. Connect once from workspace settings, then call them from workflows (ctx.integrations.invoke) or from generated apps via named queries. No OAuth boilerplate, no token juggling, no per-app SDK to install.

What integrations do

An integration is a first-class connection to an external service that your project can invoke server-side. The registry gives you:

• A single catalog UI for discovery — search by name, filter by category, one-click Connect.
• OAuth flows handled by the platform (state, PKCE, token refresh, scope negotiation).
• Encrypted credential vault — envelope encryption per workspace, with a legacy pgp_sym fallback keyed by ENCRYPTION_KEY.
• A uniform ctx.integrations.invoke(id, action, input) runtime API — the same shape whether you are talking to Slack, Stripe, or GitHub.
• Convenience helpers on ctx.messages.* for email (Resend / SendGrid / Gmail), SMS (Twilio), WhatsApp, and Telegram.

Categories

The registry is organised into six category files. Below is a sampler — the full live list is in the catalog UI (GET /integrations/catalog).

Each entry in the registry looks like this (trimmed):

{
  id: "slack",
  displayName: "Slack",
  description: "Send messages, manage channels, react to events.",
  category: "communication",
  authType: "oauth2",
  oauth2Config: {
    authUrl: "https://slack.com/oauth/v2/authorize",
    tokenUrl: "https://slack.com/api/oauth.v2.access",
    scopes: ["chat:write", "channels:read", "users:read"],
  },
  actions: ["send_message", "create_channel", "update_message"],
  tier: "built_in",
}

How to connect

1. Workspace admin enables the integration. In /admin?tab=integrations, an owner or admin toggles the integrations that members of this workspace may connect. Unenabled integrations do not appear in the member-facing catalog.
2. Member clicks Connect. In workspace Settings → Integrations, pick the app. For oauth2, the platform issues GET /integrations/oauth/:id/authorize, builds the provider authorization URL (with state and PKCE where the provider requires it), and opens the provider’s consent screen.
3. Callback and token exchange. The provider redirects to /integrations/oauth/callback. The server verifies state, exchanges the code for tokens, and writes an integration_connections row.
4. Credentials stored encrypted. Access and refresh tokens (or API keys for secret_text / custom_auth providers) are envelope-encrypted per workspace and written to credentials_encrypted. The browser never sees the raw values.
5. Available at runtime. The connection appears in GET /integrations/connections?workspaceId=… with a status of active and is immediately callable from workflows and generated apps.

Connection scopes

Every connection is stored at one of three scopes. Pick the narrowest one that fits — narrower scopes reduce blast radius and let members keep personal credentials personal.

Using an integration in a workflow

Workflows get an integrations namespace on ctx. The signature is uniform across every provider:

/** @param {import("@appbricx/runtime").WorkflowContext} ctx */
export async function run(ctx) {
  const { email, plan } = ctx.trigger.payload ?? {};

  // Charge via Stripe
  const charge = await ctx.integrations.invoke("stripe", "create_payment", {
    amount: plan === "pro" ? 2900 : 900,
    currency: "usd",
    customer_email: email,
  });

  // Post to Slack
  await ctx.integrations.invoke("slack", "send_message", {
    channel: "#signups",
    text: `New ${plan} signup: ${email} (${charge?.id ?? "no id"})`,
  });

  // Add to HubSpot
  await ctx.integrations.invoke("hubspot", "create_or_update_contact", {
    email,
    plan,
  });

  return { ok: true };
}

The exact action names and input props come from the underlying Activepieces piece package. Load them from GET /integrations/catalog/:id/actions at build time, or ask the agent — it introspects the registry and generates the correctly-shaped invoke call for you.

Convenience helpers

Common messaging paths have short-form helpers on ctx.messages.*. Each is a thin wrapper over ctx.integrations.invoke:

await ctx.messages.email({
  provider: "resend", // or "sendgrid" | "gmail"
  to: "user@example.com",
  subject: "Welcome",
  html: "<h1>Hi there</h1>",
});

await ctx.messages.sms({ to: "+15555550123", body: "Your code is 4711" });

await ctx.messages.whatsapp({
  to: "+15555550123",
  template: "otp_login",
});

await ctx.messages.telegram({ chatId: 123456, text: "Deploy finished" });

Using an integration from a generated app

Generated React apps never call third-party APIs directly — that would require shipping credentials to the browser. Instead:

• Expose the integration through a named query or a workflow. The React side calls runtime.queries.run("name", args) or runtime.workflows.invoke("name", { payload }).
• For webhooks coming from a provider (Stripe events, GitHub pushes, Slack slash-commands), point the provider at POST /hooks/:projectId/:name — see Webhooks & schedules.
• The auto-CRUD REST API and named queries can be authorised with the end-user’s session, so your workflow sees the user who triggered it via ctx.userId.

Admin control

Integrations are per-workspace. What you see in an app’s connect catalog is the intersection of the platform-wide enablement list and the workspace’s own enablement list.

Security

• Encrypted at rest. Every connection row stores credentials in credentials_encrypted. New rows use the envelope-v1 format keyed per workspace; legacy rows use pgp_sym keyed by ENCRYPTION_KEY. Reads auto-detect the format.
• Never exposed to the browser. The catalog and connections endpoints return display metadata (id, displayName, scope, status) — never the token itself. All invocation happens server-side inside a workflow.
• Scoped access. A user-scoped connection is only usable when a workflow runs on behalf of that user. A project-scoped connection is only usable inside that project.
• Revocable. Deleting a connection removes the row and the encrypted blob. If the provider supports token revocation, it is also called on delete. Rotate ENCRYPTION_KEY via the operator re-encryption path.
• OAuth state and PKCE. State is signed, single-use, and TTL-bound. PKCE is used automatically for providers that require or benefit from it.
• Least-privilege scopes. Registry entries list only the scopes each set of actions actually needs — no *:read *:write catch-alls.

Adding a custom integration

The registry is an Appbricx-side extension surface, not a runtime plugin surface. New integrations are added by editing the server registry and (usually) installing an Activepieces piece package:

1. Add an entry to one of the category files under services/api/src/integrations/registry/*.ts — or the hand-curated services/api/src/integrations/registry.ts which overrides the others by ID.
2. Add the underlying piece package to services/api/package.json so piecePackage resolves at boot. The boot loader will silently prune any entry whose piece is not installed and log a warning.
3. For OAuth, set authType: "oauth2" and oauth2Config — the platform’s OAuth flow will do the rest. For static credentials, use secret_text or custom_auth with a customAuthFields spec.
4. Deploy the API. The new integration appears in the catalog at GET /integrations/catalog and is admin-enable-able in /admin?tab=integrations.

See the developer guide for the full registry / piece / OAuth-config schema and the CI-time check-integration-pieces.mjs guard.

Related

• Workflows — the natural home for ctx.integrations.invoke.
• Webhooks & schedules — receive events from providers and fan them into workflows.
• Secrets & env — for values you would rather keep out of the integration vault entirely (webhook shared secrets, per-project API constants).
• Bring your own key — the sibling system for AI model providers, which uses its own resolution chain rather than the integration vault.