Integrations

ContractSpec provides first-class integration support through a spec-first architecture. Integrations are defined globally, connected per-tenant, and bound to apps through typed specifications, ensuring type-safe, policy-enforced access to external services.

Spec-first architecture

Integrations in ContractSpec follow a three-layer model:

1. IntegrationSpec (Global)

Defines what an integration provides: capabilities, configuration schema, secrets, webhooks, and requirements.

Learn more →

2. IntegrationConnection (Per-Tenant)

A tenant's configured connection with credentials, environment (sandbox/production), and health status.

Learn more →

3. AppIntegrationBinding (Per-App)

Maps tenant connections to app capabilities and workflows, defining which operations can use which integrations.

Learn more →

Integration categories

type IntegrationCategory =
  | "payments"      // Stripe
  | "email"         // Postmark, Resend, Gmail
  | "calendar"      // Google Calendar
  | "sms"           // Twilio
  | "ai-llm"        // OpenAI
  | "ai-voice"      // ElevenLabs
  | "speech-to-text" // OpenAI Whisper
  | "vector-db"     // Qdrant
  | "storage"       // S3-compatible
  | "open-banking"  // Powens (read-only)
  | "accounting"    // Coming soon
  | "crm"           // Coming soon
  | "helpdesk"      // Coming soon
  | "custom";       // User-defined

Available integrations

Payments

Stripe

Payment processing, subscriptions, and invoicing

Open Banking

Powens (Read-Only)

Account, transaction, and balance synchronisation via Powens with tenant-owned credentials.

Email

Postmark

Transactional email delivery with high deliverability

Resend

Modern email API for developers

Gmail API

Inbound email processing and thread management

Calendar & Scheduling

Google Calendar

Event scheduling and calendar management

AI & Machine Learning

OpenAI

LLMs, embeddings, and Whisper speech-to-text

ElevenLabs

Text-to-speech and voice synthesis

Qdrant

Vector database for semantic search and RAG

Storage

S3-Compatible Storage

Object storage (AWS S3, Scaleway, MinIO, etc.)

SMS & Messaging

Twilio

SMS notifications and messaging

How integrations work

ContractSpec integrations are implemented as capability providers. This means:

  • Type safety – All API calls are type-checked by TypeScript and validated at runtime via Zod
  • Policy enforcement – Access to external services is governed by your PolicySpecs
  • Audit logging – All integration calls are automatically logged
  • Error handling – Built-in retries and fallback strategies
  • Environment-based config – API keys and secrets are managed through environment variables

Secret management

Secrets are resolved through a layered secret provider manager. It checks lightweight environment overrides first, then falls back to a managed vault (Google Cloud Secret Manager) for production.

Environment variables

Perfect for local development and secure staging overrides. Use the env:// scheme or append ?env= to another reference to map an explicit variable.

# Override a production secret locally
CONTRACTSPEC__SECRET__STRIPE=sk_test_123

# Reference
env://CONTRACTSPEC__SECRET__STRIPE

GCP Secret Manager

Used in production to store versioned credentials with rotation support. References follow the gcp://projects/.../secrets/.../versions/latest format.

# Production reference
gcp://projects/tenant/secrets/stripe-secret-key/versions/latest

The secret manager chooses the first provider that can resolve a reference, so local environment variables can override the managed vault without changing blueprints or tenant configs.

Configuration

Integrations are configured through environment variables and secret references. Here's a typical setup:

# .env
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

POSTMARK_API_TOKEN=...
POSTMARK_FROM_EMAIL=noreply@example.com

OPENAI_API_KEY=sk-...
OPENAI_ORGANIZATION=org-...

QDRANT_URL=https://...
QDRANT_API_KEY=...

S3_ENDPOINT=https://s3.fr-par.scw.cloud
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_BUCKET=my-bucket
S3_REGION=fr-par

# Secret references
STRIPE_SECRET_REF=gcp://projects/tenant/secrets/stripe-secret-key/versions/latest
STRIPE_SECRET_OVERRIDE=env://STRIPE_SECRET_KEY

Integration categories

ContractSpec supports the following integration categories:

type IntegrationCategory =
  | "payments"        // Stripe, PayPal, etc.
  | "email"           // Postmark, Resend, Gmail
  | "calendar"        // Google Calendar, Outlook
  | "sms"             // Twilio, MessageBird
  | "ai-llm"          // OpenAI, Anthropic, Cohere
  | "ai-voice"        // ElevenLabs, Google TTS
  | "speech-to-text"  // OpenAI Whisper, Google STT
  | "vector-db"       // Qdrant, Pinecone, Weaviate
  | "storage"         // S3, GCS, Azure Blob
  | "accounting"      // QuickBooks, Xero (coming soon)
  | "crm"             // Salesforce, HubSpot (coming soon)
  | "helpdesk"        // Zendesk, Intercom (coming soon)
  | "custom";         // Your own integrations

Custom integrations

You can create custom integrations by implementing a capability provider. See the Custom Providers guide for details.

Get Started with Stripe