APIs¶

Target Architecture — Final-State Design

This page defines the final-state API surface of the Integration Platform. All public APIs are versioned REST over HTTPS, authenticated with OAuth2 bearer tokens, tenant-scoped, and instrumented so every request is correlated by traceId. Internal service-to-service calls use gRPC.

The Integration Platform exposes a deliberately small public surface — connection lifecycle, provider registration, webhook subscription and delivery, run inspection, and credential rotation — backed by richer internal contracts. All resource paths follow the naming conventions: plural, lowercase, hyphenated collection nouns, with verb sub-paths for non-CRUD actions.

Public REST APIs¶

Method	Path	Purpose	Owning Service
`POST`	`/integrations/connections`	Establish a new integration connection	Source-control / cloud / comms services
`GET`	`/integrations/connections/{connectionId}`	Retrieve a connection and its health	Owning integration service
`POST`	`/integrations/providers`	Register a provider in the Vendor Registry	`VendorApiClientRegistryService`
`POST`	`/webhooks/subscriptions`	Create an outbound webhook subscription	`WebhookGatewayService`
`POST`	`/webhooks/deliveries`	Ingest an inbound webhook delivery	`WebhookGatewayService`
`GET`	`/integrations/runs/{runId}`	Retrieve an integration run and its outcome	Owning integration service
`POST`	`/integrations/credentials/rotate`	Rotate a stored credential	`VendorApiClientRegistryService`

Internal APIs¶

Model invocation (OpenAIIntegrationService, AzureOpenAIIntegrationService, OllamaIntegrationService) — gRPC Complete, Embed, Stream contracts consumed by the Agent Mesh. Not part of the public surface; governed, rate-limited, and audited.
Tool invocation (McpConnectorService) — gRPC ListTools, InvokeTool bridging MCP tool servers to agents.
Communication dispatch (EmailIntegrationService, SmsIntegrationService) — internal SendEmail / SendSms consumed via MassTransit commands from the Control Plane.
Commerce & business (PaymentIntegrationService, CrmIntegrationService, SupportIntegrationService) — internal command consumers; external interaction is via reconciled webhooks.

gRPC¶

Internal service-to-service traffic uses gRPC with protobuf contracts for low-latency, high-throughput paths (model streaming, tool invocation). gRPC services share the same OAuth2 + tenantId authorization context as REST and propagate traceId/correlationId via metadata headers. Public partners never call gRPC directly; the REST surface above is the only externally reachable contract.

Authorization¶

Authentication — OAuth2 bearer tokens (client-credentials for service callers, authorization-code for Factory Studio users) issued by the factory identity provider. Vendor-facing OAuth2 token lifecycles are handled by ConnectSoft.Extensions.Http.OAuth2.
Authorization — scope- and role-based. Representative scopes: integration.connections.write, integration.connections.read, integration.providers.write, webhooks.subscriptions.write, webhooks.deliveries.ingest, integration.runs.read, integration.credentials.rotate.
Tenant isolation — every request carries tenantId (token claim); handlers assert it against the target resource before any store or vendor call.
Inbound webhook auth — POST /webhooks/deliveries authenticates by vendor signature (HMAC/JWS) plus a per-subscription secret, not a bearer token. See Security.

Versioning¶

Path-stable, header-versioned: clients send Accept: application/vnd.connectsoft.integration.v1+json; the default is the current major.
Additive changes (new optional fields) are non-breaking. Breaking changes increment the major version and are offered side-by-side during a deprecation window.
Event payloads follow the independent cs-schema-version rule from the event envelope.

Examples¶

Establish a connection¶

POST /integrations/connections
Authorization: Bearer <token>
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "providerId": "prov-github",
  "displayName": "Booking SaaS GitHub",
  "authMode": "OAuth2ClientCredentials",
  "credentialRef": "kv://factory-integration/github-booking",
  "configuration": {
    "organization": "connectsoft-booking",
    "defaultBranch": "main"
  }
}

{
  "connectionId": "conn-7b3c1f9a",
  "status": "Active",
  "providerId": "prov-github",
  "health": "Healthy",
  "establishedAt": "2026-06-11T09:00:00Z",
  "traceId": "trace-9f1c2b7d"
}

Retrieve a connection¶

GET /integrations/connections/conn-7b3c1f9a
Authorization: Bearer <token>

{
  "connectionId": "conn-7b3c1f9a",
  "tenantId": "connectsoft",
  "providerId": "prov-github",
  "status": "Active",
  "health": "Healthy",
  "lastCheckedAt": "2026-06-11T08:59:00Z",
  "credentialRef": "kv://factory-integration/github-booking",
  "lastRunId": "run-3a6e1d40"
}

Register a provider¶

POST /integrations/providers
Authorization: Bearer <token>
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "key": "twilio-sms",
  "displayName": "Twilio SMS",
  "category": "Communication",
  "authModel": "ApiKey",
  "apiClient": "ConnectSoft.Sms.Providers.Twilio",
  "capabilities": ["sms.send", "sms.status"],
  "baseUrl": "https://api.twilio.com"
}

{
  "providerId": "prov-twilio-sms",
  "status": "Registered",
  "apiClientId": "client-twilio-v1",
  "registeredAt": "2026-06-11T09:01:00Z"
}

Create an outbound webhook subscription¶

POST /webhooks/subscriptions
Authorization: Bearer <token>
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "eventType": "DeploymentPromoted",
  "endpointUrl": "https://hooks.partner.example/connectsoft",
  "signingSecretRef": "kv://factory-integration/partner-hook-secret",
  "active": true
}

{
  "subscriptionId": "sub-31f8c0a2",
  "status": "Active",
  "eventType": "DeploymentPromoted",
  "createdAt": "2026-06-11T09:02:00Z"
}

Ingest an inbound webhook delivery¶

POST /webhooks/deliveries
X-CS-Provider: github
X-Hub-Signature-256: sha256=...
Content-Type: application/json

{
  "providerDeliveryId": "gh-12345",
  "eventName": "pull_request",
  "payload": { "action": "closed", "merged": true }
}

{
  "deliveryId": "del-5e10c3d2",
  "status": "Accepted",
  "normalizedEventType": "PullRequestMerged",
  "traceId": "trace-9f1c2b7d"
}

Retrieve an integration run¶

GET /integrations/runs/run-3a6e1d40
Authorization: Bearer <token>

{
  "runId": "run-3a6e1d40",
  "connectionId": "conn-7b3c1f9a",
  "operation": "OpenPullRequest",
  "status": "Completed",
  "attempts": 1,
  "startedAt": "2026-06-11T09:03:00Z",
  "completedAt": "2026-06-11T09:03:02Z",
  "traceId": "trace-9f1c2b7d"
}

Rotate a credential¶

POST /integrations/credentials/rotate
Authorization: Bearer <token>
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "credentialId": "cred-github-booking",
  "reason": "ScheduledRotation"
}

{
  "credentialId": "cred-github-booking",
  "status": "Rotating",
  "newVersionRef": "kv://factory-integration/github-booking?version=2",
  "verificationRunId": "run-9c4b22e1"
}