Integrations

Connect Backbuild with third-party services. Manage Stripe Connect accounts and communication providers for your organization.

After reading this page you will be able to: connect a Stripe account per package and environment, configure an email or SMS provider with credentials that are encrypted and never echoed back, test a provider before you rely on it, and route specific categories of outbound email through your own provider. Every secret you supply here is stored by reference and is never returned in any API response.

Stripe Connect

Stripe Connect integrations are configured per SaaS package and per environment (development, staging, production).

Create Stripe Connection

POST /v1/stripe-connect

Request Body

{
  "saas_package_id": "...",
  "environment": "production",
  "stripe_account_id": "acct_...",
  "account_type": "express",
  "publishable_key": "pk_live_...",
  "webhook_secret_ref": "...",
  "business_profile": { }
}

The organization is taken from the authenticated session. Connections reference a Stripe Connect account (stripe_account_id) rather than storing raw secret keys inline; sensitive values are held by reference. The environment is one of development, staging, preprod, or production. Do not send created_at, updated_at, or org_id in the request body; these are assigned by the server.

Response

A successful create returns 201 Created with the complete connection record inside the standard envelope. Each connection is addressed by its (SaaS package, environment) pair. Status flags start false until onboarding completes, and secret values are never returned.

{
  "success": true,
  "data": {
    "org_id": "...",
    "saas_package_id": "...",
    "environment": "production",
    "stripe_account_id": "acct_...",
    "account_type": "express",
    "charges_enabled": false,
    "payouts_enabled": false,
    "onboarding_complete": false,
    "publishable_key": "pk_live_...",
    "business_profile": { },
    "webhook_secret_ref": "...",
    "created_by": "...",
    "created_at": "2026-04-12T15:30:00Z",
    "updated_at": "2026-04-12T15:30:00Z"
  }
}

Response Codes

Get Stripe Connection

GET /v1/stripe-connect

Query Parameters

Returns connection metadata. Secret values are never returned in API responses.

Update Stripe Connection

PUT /v1/stripe-connect

Request Body

{
  "saas_package_id": "...",
  "environment": "production",
  "account_type": "express",
  "publishable_key": "pk_live_new_...",
  "webhook_secret_ref": "..."
}

Communication Providers

Configure email and SMS providers for your SaaS integrations. The organization is taken from the authenticated session. Provider credentials are encrypted at rest and are never returned in API responses.

Supported Providers

List Integrations

GET /v1/saas/integrations

Lists all configured SaaS provider integrations for the organization.

Configure Provider

POST /v1/saas/integrations/configure

Non-secret settings go under config; credentials go under secrets (at least one secret is required). Secret values are encrypted and stored by reference; they are never echoed back.

Request Body (Resend example)

{
  "provider": "resend",
  "config": {},
  "secrets": {
    "api_key": "re_..."
  }
}

Email providers do not take a sender identity in their configuration. The From address and display name of each outbound email are derived per send from the sending mailbox, never from integration settings.

Request Body (Twilio example)

{
  "provider": "twilio",
  "config": {},
  "secrets": {
    "account_sid": "AC...",
    "auth_token": "..."
  }
}

The organization is taken from the authenticated session. Do not send id, created_at, updated_at, or org_id in the request body; these are assigned by the server.

Response

A successful configure returns 201 Created with the complete integration record inside the standard envelope. The returned config contains only your non-secret settings; secret values and their internal references are never echoed back.

{
  "success": true,
  "data": {
    "integration": {
      "id": "...",
      "org_id": "...",
      "provider": "resend",
      "integration_type": "saas_provider",
      "config": {},
      "status": "active",
      "last_sync_at": null,
      "error_message": null,
      "created_by": "...",
      "created_at": "2026-04-12T15:30:00Z",
      "updated_at": "2026-04-12T15:30:00Z"
    }
  }
}

Response Codes

Test Provider Connectivity

POST /v1/saas/integrations/:id/test

Runs a read-only connectivity probe against the configured provider. Credentials are never exposed in the response.

Disconnect Provider

DELETE /v1/saas/integrations/:id

Outbound Email Send Scopes

An organization with a connected email provider (resend, sendgrid, or ses) chooses which categories of outbound email route through that provider. Scopes are non-secret routing configuration; any combination of all_outbound, marketing, transactional, and system is accepted. all_outbound matches every send from the organization’s domain, and a categorized send also matches its own scope.

When a send matches a scope, it is dispatched through the organization’s own provider key ahead of the platform sender. There is no platform fallback on a provider error: if the organization’s provider rejects the send, the error is surfaced rather than silently rerouted, so misconfiguration (for example, an unverified domain on the provider account) is visible.

Get Send Scopes

GET /v1/org-integrations/:provider/send-scopes

Response

{
  "success": true,
  "data": {
    "scopes": ["transactional", "system"]
  }
}

Set Send Scopes

PUT /v1/org-integrations/:provider/send-scopes

Request Body

{
  "scopes": ["all_outbound"]
}

Replaces the routing scopes for the provider. Requires the integration management permission. A provider outside the supported set returns 400; setting scopes for a provider that is not connected returns 409.

Frequently Asked Questions