Skip to content

Control Plane — APIs

The Control Plane exposes a consistent API surface across all microservices. APIs follow the Naming Conventions (plural, lowercase, hyphenated collection nouns; verb sub-paths for non-CRUD actions), are versioned, tenant-scoped, and secured with OpenIddict-based bearer tokens.

Target Architecture — Final-State Design

The endpoints below are representative of the final-state target surface. Public APIs are consumed by Factory Studio and external automation; internal APIs and gRPC are service-to-service within the factory mesh.

API Tiers

Tier Audience Protocol Auth Notes
Public Factory Studio, external automation REST/JSON over HTTPS OpenIddict bearer (user or API token) Behind ConnectSoft.ApiGatewayTemplate; rate-limited and quota-checked.
Internal Service-to-service (orchestration) REST/JSON OpenIddict client-credentials (service identity) Not exposed at the gateway.
gRPC High-throughput intra-mesh calls gRPC/protobuf Client-credentials via ConnectSoft.Extensions.Saas.AspNetCore.Grpc Used for task assignment, policy evaluation, state projection.
Async Event-driven integration MassTransit / Service Bus Message-level (see Events) Canonical envelope.

Authorization Model

Every request is authorized against tenant and project scope plus a permission:

  • The bearer token carries tenantId, subject (user or service identity), and granted scopes.
  • ConnectSoft.Extensions.Saas.AspNetCore resolves the tenant context and applies tenant filters before any handler runs.
  • The AuthorizationService resolves permissions (e.g. workflow:start, approval:grant, blueprint:publish); the gateway enforces edition entitlements and QuotaService checks quota.
  • Sensitive operations additionally pass through PolicyEngineService and may open an ApprovalRequest (see Workflows).
GET /api/v1/projects HTTP/1.1
Authorization: Bearer eyJhbGciOi...
X-Tenant-Id: connectsoft
Accept: application/json

Versioning

  • URI versioning: /api/v{major}/... (e.g. /api/v1/workflows/instances). Major version only changes on breaking contracts.
  • Additive evolution: new optional fields and endpoints are non-breaking and do not bump the major version.
  • Deprecation: deprecated endpoints return Deprecation and Sunset headers and are tracked as integration changes.
  • Event contracts version independently via eventType suffixes (ArtifactCreatedV2) and cs-schema-version (see Event Envelope).

Representative Endpoints by Context

Identity & Access

POST /api/v1/api-tokens

{
  "name": "ci-release-bot",
  "scopes": ["workflow:start", "artifact:read"],
  "projectId": "proj-booking-saas",
  "expiresAt": "2026-12-31T00:00:00Z"
}

Response 201 Created:

{
  "apiTokenId": "tok-9f21",
  "tenantId": "connectsoft",
  "token": "cst_live_…redacted…",
  "scopes": ["workflow:start", "artifact:read"],
  "status": "Active"
}

Tenant & Edition

POST /api/v1/tenants

{ "slug": "contoso", "displayName": "Contoso Ltd", "editionId": "ed-scale", "region": "westeurope" }

Response 201 Created (emits TenantProvisioned):

{ "tenantId": "contoso", "editionId": "ed-scale", "status": "Provisioning" }

Project Management

POST /api/v1/projects

{
  "name": "Booking SaaS",
  "slug": "booking-saas",
  "description": "Multi-tenant reservations platform",
  "environments": ["dev", "staging", "prod"]
}

Response 201 Created (emits ProjectCreated):

{ "projectId": "proj-booking-saas", "tenantId": "connectsoft", "status": "Active" }

Blueprint Management

POST /api/v1/blueprints/{blueprintId}/validate

{ "blueprintVersionId": "bpv-12", "rules": ["schema", "naming", "dependency", "policy"] }

Response 200 OK (emits BlueprintValidated or BlueprintValidationFailed):

{
  "blueprintId": "bp-service-reservations",
  "blueprintVersionId": "bpv-12",
  "passed": true,
  "violations": []
}

Workflow Orchestration

POST /api/v1/workflows/instances

{
  "workflowDefinitionId": "wfd-project-bootstrap",
  "workflowDefinitionVersion": "4.1.0",
  "projectId": "proj-booking-saas",
  "inputs": { "blueprintId": "bp-service-reservations", "intent": "Bootstrap reservations service" }
}

Response 202 Accepted (emits WorkflowInstanceStarted):

{
  "workflowInstanceId": "wf-7781",
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "state": "Running",
  "traceId": "trace-9f1c2b7d",
  "correlationId": "corr-3a6e1d40"
}

Read process state:

GET /api/v1/workflows/instances/wf-7781/state

{
  "workflowInstanceId": "wf-7781",
  "state": "AwaitingApproval",
  "currentStep": "ReleaseGate",
  "completedSteps": ["BlueprintValidated", "DomainModelGenerated", "MicroserviceAssembly"],
  "openApprovals": ["apr-55"]
}

Agent Tasks

GET /api/v1/agent-tasks/task-4d21

{
  "taskId": "task-4d21",
  "workflowInstanceId": "wf-7781",
  "agentRole": "SolutionArchitect",
  "requestedSkill": "ConnectSoft.Skill.DesignServiceBlueprint",
  "status": "Completed",
  "outputArtifacts": ["art-serviceblueprint-reservations-1"]
}

The full task assignment/result contract is the canonical Agent Task Contract.

Governance — Policies

POST /api/v1/policies/evaluate

{
  "subject": { "agentRole": "ReleaseManager", "projectId": "proj-booking-saas" },
  "action": "release:promote",
  "resource": { "environment": "prod", "moduleId": "module-reservations-api" },
  "context": { "workflowInstanceId": "wf-7781" }
}

Response 200 OK (emits PolicyDecisionRecorded):

{
  "policyDecisionId": "pd-901",
  "effect": "RequireApproval",
  "matchedPolicy": "pol-prod-release-gate",
  "obligations": ["approval:ReleaseManager"]
}

Governance — Approvals

POST /api/v1/approvals/apr-55/grant

{ "decidedBy": "user-amelia", "comment": "Release reviewed and approved", "decision": "Granted" }

Response 200 OK (emits ApprovalGranted):

{ "approvalId": "apr-55", "status": "Granted", "workflowInstanceId": "wf-7781" }

Governance — Audit

GET /api/v1/audit?projectId=proj-booking-saas&from=2026-06-01&to=2026-06-11

{
  "items": [
    { "auditEntryId": "aud-1", "action": "release:promote", "actor": "user-amelia", "occurredAt": "2026-06-11T00:20:00Z", "outcome": "Granted" }
  ],
  "continuationToken": null
}

Cost & Usage

GET /api/v1/usage/rollups?tenantId=connectsoft&period=2026-06

{
  "tenantId": "connectsoft",
  "period": "2026-06",
  "tokens": 18420113,
  "agentTasks": 5120,
  "computeMinutes": 9043,
  "byProject": [{ "projectId": "proj-booking-saas", "tokens": 14210980 }]
}

Integration

POST /api/v1/integrations

{
  "type": "GitProvider",
  "provider": "AzureDevOps",
  "displayName": "Contoso ADO",
  "configRef": "kv://control-plane/integrations/ado-contoso"
}

Response 201 Created (emits IntegrationConnected):

{ "integrationConnectionId": "int-77", "status": "Connected", "type": "GitProvider" }

Error Contract

All services return a consistent problem-details body:

{
  "type": "https://docs.connectsoft.ai/errors/quota-exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "detail": "Monthly agent-task quota for edition 'scale' exceeded.",
  "tenantId": "connectsoft",
  "traceId": "trace-9f1c2b7d"
}

gRPC Surface (selected)

Service RPC Purpose
TaskAssignmentService AssignTask, ReassignTask Place/replace agent tasks at high throughput.
PolicyEngineService Evaluate Synchronous policy decision in the orchestration hot path.
ProcessStateService GetState, StreamState Read/stream workflow & task state projections.
QuotaService CheckQuota, Consume Inline quota enforcement.