OSS-first docs
These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.
Integration Spec Model
Integrations in ContractSpec are defined through typed specifications that declare capabilities, configuration requirements, and connection details. This page covers IntegrationSpec and IntegrationConnection.
IntegrationSpec
The IntegrationSpec is a global definition of an integration provider. It declares what the integration provides and what it requires.
type IntegrationSpec = {
id: string;
label: string;
description: string;
category: IntegrationCategory;
// Capabilities this integration provides
providesCapabilities: {
capabilityId: string;
operation: string;
description: string;
}[];
// Dependencies
requirements: {
capabilities?: string[]; // e.g., ["billing.core", "auth.session"]
minVersion?: string;
};
// Configuration schema (non-secret)
configSchema: {
[key: string]: {
type: string;
description: string;
required?: boolean;
default?: unknown;
};
};
// Secret schema (for keys, tokens)
secretSchema: {
[key: string]: {
type: string;
description: string;
required: boolean;
};
};
// Webhook support
webhooks?: {
supported: boolean;
events: string[];
signatureHeader?: string;
};
// Documentation
docsUrl?: string;
setupGuideUrl?: string;
// Metadata
version: string;
createdAt: string;
updatedAt: string;
};Example: Stripe IntegrationSpec
{
id: "stripe",
label: "Stripe",
description: "Payment processing and subscription management",
category: "payments",
providesCapabilities: [
{
capabilityId: "payments.createPaymentIntent",
operation: "createPaymentIntent",
description: "Create a payment intent for checkout"
},
{
capabilityId: "payments.createSubscription",
operation: "createSubscription",
description: "Create a recurring subscription"
},
{
capabilityId: "payments.refund",
operation: "refund",
description: "Refund a payment"
}
],
requirements: {
capabilities: ["billing.core"],
minVersion: "1.0.0"
},
configSchema: {
webhookUrl: {
type: "string",
description: "URL to receive Stripe webhooks",
required: false
}
},
secretSchema: {
apiKey: {
type: "string",
description: "Stripe secret API key (sk_...)",
required: true
},
webhookSecret: {
type: "string",
description: "Webhook signing secret (whsec_...)",
required: false
}
},
webhooks: {
supported: true,
events: [
"payment_intent.succeeded",
"payment_intent.payment_failed",
"customer.subscription.created",
"customer.subscription.updated",
"customer.subscription.deleted"
],
signatureHeader: "stripe-signature"
},
docsUrl: "https://docs.contractspec.com/integrations/stripe",
setupGuideUrl: "https://stripe.com/docs/keys",
version: "1.0.0"
}IntegrationConnection
An IntegrationConnection is a per-tenant instance of an integration with configured credentials and environment settings.
type IntegrationConnection = {
id: string;
tenantId: string;
integrationId: string;
// Environment
environment: "sandbox" | "production";
// Configuration (non-secret)
config: Record<string, unknown>;
// Secret reference (encrypted, never exposed)
secretRef: string;
// Status
status: "connected" | "disconnected" | "error";
lastHealthCheck?: string;
lastHealthCheckStatus?: "success" | "failure";
lastErrorMessage?: string;
// Metadata
createdAt: string;
updatedAt: string;
createdBy: string;
};Example: Stripe IntegrationConnection
// Production connection
{
id: "conn_stripe_acme_prod",
tenantId: "acme-corp",
integrationId: "stripe",
environment: "production",
config: {
webhookUrl: "https://acme.app/webhooks/stripe"
},
secretRef: "secret_stripe_acme_prod_v1",
status: "connected",
lastHealthCheck: "2025-01-15T10:30:00Z",
lastHealthCheckStatus: "success",
createdAt: "2025-01-01T00:00:00Z",
updatedAt: "2025-01-15T10:30:00Z",
createdBy: "admin@acme.com"
}
// Sandbox connection
{
id: "conn_stripe_acme_test",
tenantId: "acme-corp",
integrationId: "stripe",
environment: "sandbox",
config: {
webhookUrl: "https://sandbox.acme.app/webhooks/stripe"
},
secretRef: "secret_stripe_acme_test_v1",
status: "connected",
lastHealthCheck: "2025-01-15T10:25:00Z",
lastHealthCheckStatus: "success",
createdAt: "2025-01-01T00:00:00Z",
updatedAt: "2025-01-15T10:25:00Z",
createdBy: "dev@acme.com"
}Example: Messaging IntegrationConnection
Messaging providers use the same spec + connection model, then route inbound events through the channel runtime for signature validation, idempotent ingestion, policy decisions, and outbox-backed dispatch.
{
id: "conn_slack_acme_prod",
tenantId: "acme-corp",
integrationId: "messaging.slack",
environment: "production",
config: {
defaultChannelId: "C0123456789",
apiBaseUrl: "https://slack.com/api"
},
secretRef: "secret_slack_acme_prod_v1",
status: "connected"
}
// secret payload behind secretRef
{
"botToken": "xoxb-...",
"signingSecret": "..."
}Health transport strategy config
Health providers support deterministic transport routing and explicit unofficial gating in connection config.
{
"defaultTransport": "official-api",
"strategyOrder": ["official-api", "aggregator-api", "unofficial"],
"allowUnofficial": false,
"unofficialAllowList": ["health.peloton"],
"mcpUrl": "https://mcp.provider.example",
"oauthTokenUrl": "https://api.provider.example/oauth/token"
}
// secret payload behind secretRef
{
"accessToken": "...",
"refreshToken": "...",
"clientId": "...",
"clientSecret": "...",
"tokenExpiresAt": "2026-02-01T00:00:00.000Z",
"mcpAccessToken": "..."
}Health checks
IntegrationConnections are periodically health-checked to ensure they remain valid:
- API key validation - Test that credentials are still valid
- Connectivity check - Verify network access to the provider
- Permission verification - Ensure required scopes are granted
- Webhook validation - Test webhook endpoint reachability
Failed health checks update the connection status to "error" and trigger alerts.
Secret management
Secrets (API keys, tokens) are never stored in plaintext:
- User provides secrets through secure UI or API
- Secrets are encrypted using tenant-specific keys
- Encrypted secrets are stored in secure vault (e.g., AWS Secrets Manager)
- IntegrationConnection stores only a reference (secretRef)
- At runtime, secrets are decrypted on-demand and never logged
Best practices
- Always maintain separate sandbox and production connections
- Use descriptive connection IDs that include tenant and environment
- Monitor health check status and set up alerts for failures
- Rotate secrets regularly and update secretRef accordingly
- Document the purpose and ownership of each connection
- Test connections in sandbox before enabling in production
Integrations overview
Understand the binding model for external services, providers, and tenant-owned connections.
OpenAI integration
Connect OpenAI through typed capabilities, explicit provider config, and governed runtime usage.
Why ContractSpec
Keep educational and comparison content reachable without letting it define the primary OSS learning path.