Integration Governance & Identity

Milestone 2C introduced durable, Postgres-backed identity (ManagementPrincipal/TenantMembership/PrincipalCredential). Milestone 2D built the full Integration Governance lifecycle on top of it — a real customer integration progresses through documented, auditable states from "just created" to "serving production traffic," gated at every step by an explicit platform-admin approval or automated check. This page is the API reference for both; the interactive, always-current version is $CARC_RUNTIME_API_URL/docs (Scalar, generated from services/runtime-control-engine/openapi/openapi.yaml) and $CARC_RUNTIME_API_URL/openapi.json for the raw document.

See SDK Guide for the CarcManagementClient/CarcAdminClient methods that wrap every route below, and Security for the credential-plane separation this lifecycle depends on.

Principal and credential operations

Every human or service that talks to this platform (other than the integration-runtime execution gateway — see below) is a ManagementPrincipal. A platform admin creates and manages them:

POST   /admin/management-principals                       # create (status: active on creation)
GET    /admin/management-principals                        # list
GET    /admin/management-principals/:id
POST   /admin/management-principals/:id/suspend
POST   /admin/management-principals/:id/disable            # terminal

POST   /admin/management-principals/:id/memberships         # grant a TenantMembership (status: active on creation)
GET    /admin/management-principals/:id/memberships
PATCH  /admin/tenant-memberships/:id/role
POST   /admin/tenant-memberships/:id/activate
POST   /admin/tenant-memberships/:id/suspend
POST   /admin/tenant-memberships/:id/revoke                 # terminal

POST   /admin/management-principals/:id/credentials         # issue — the ONE-TIME response carrying the raw secret
GET    /admin/management-principals/:id/credentials         # list — secret-free PrincipalCredentialView only
POST   /admin/principal-credentials/:id/rotate               # a new secret; the old one keeps working during the overlap window
POST   /admin/principal-credentials/:id/revoke               # terminal, effective on the very next request

GET /admin/bootstrap-status reports whether bootstrap-admin access is enabled and whether a durable platform_admin already exists — see docs/deployment/staging-integration-governance.md's bootstrap sequence for why this exists and how to use it safely.

Integration lifecycle

draft ──submit──▶ submitted ──approve-sandbox──▶ sandbox-approved
                                                        │
                                          request-certification
                                                        ▼
                                          certification-pending ──approve-production──▶ production-approved ──activate──▶ active
                                                                                                                              │
                                                                                                            suspend ◀─────────┤────▶ deprecated
                                                                                                               │
                                                                                                            activate (resume)
                                                                                                               │
                                                                                                               ▼
                                                                                                            active

revoked is reachable from every non-terminal state above and is itself terminal.

• POST /runtime/integrations (tenant-facing, integration:create) — create a draft.
• PATCH /runtime/integrations/:id (tenant-facing, integration:update) — edit allowed metadata (name/description/owner_team/technical_contact) at any point before revoked.
• POST /runtime/integrations/:id/submit (tenant-facing, integration:submit).
• POST /admin/integrations/:id/approve-sandbox — requires the tenant's OrganizationVerification to already be verified (see below).
• POST /admin/integrations/:id/request-certification — the integration's own state transition; distinct from requesting an IntegrationCertification record against one environment (below), which this state gates.
• POST /admin/integrations/:id/approve-production — requires a current, unexpired, passed IntegrationCertification for the integration's production environment specifically.
• POST /admin/integrations/:id/activate — also resumes a suspended integration straight back to active (there is no separate "unsuspend" route).
• POST /admin/integrations/:id/suspend / .../revoke — suspension is reversible (via activate); revocation is terminal.

Organization verification

A tenant cannot self-verify — there is no tenant-facing route for this at all, by design:

POST /admin/organization-verifications                  # submit/resubmit
POST /admin/organization-verifications/:id/approve
POST /admin/organization-verifications/:id/reject
POST /admin/organization-verifications/:id/suspend

Environments and agent bindings

Each Integration owns independent IntegrationEnvironments (development / sandbox / staging / production) — approving or activating one never cascades to its siblings. A production environment additionally requires the parent Integration to already be production-approved or active before it can itself be approved.

POST /admin/integrations/:id/environments                          # create (status: pending)
POST /admin/integration-environments/:id/approve
POST /admin/integration-environments/:id/activate                   # also resumes from suspended
POST /admin/integration-environments/:id/suspend
POST /admin/integration-environments/:id/revoke                     # terminal

POST  /admin/integration-environments/:id/agent-bindings             # create (status: pending)
PATCH /admin/integration-agent-bindings/:id/capabilities             # allowed_operations — an IntegrationCapability[]
POST  /admin/integration-agent-bindings/:id/approve
POST  /admin/integration-agent-bindings/:id/activate                 # also enforces one active binding per (environment, agent)
POST  /admin/integration-agent-bindings/:id/suspend
POST  /admin/integration-agent-bindings/:id/revoke                   # terminal

Certification lifecycle

A certification record is requested per environment, run against a real registered agent (the checks execute inside their own synthetic sandbox — see CertificationSuiteRunner/defaultCertificationChecks.ts — so running them never requires the live environment/agent binding to already be active), then explicitly passed or failed:

POST /admin/integration-environments/:id/certifications             # request (status: pending)
POST /admin/integration-certifications/:id/run                      # executes the platform conformance suite, returns test_results — does NOT change status
POST /admin/integration-certifications/:id/pass                     # records test_results + expires_at
POST /admin/integration-certifications/:id/fail                     # terminal for this attempt — a retry requires a new certification_version
POST /admin/integration-certifications/:id/revoke

GET /runtime/integration-environments/:id/certifications is the tenant-facing read-only equivalent — a tenant can see its own certification status but never run or decide one.

Credential bindings and the runtime execution gateway

IntegrationCredentialBinding is the credential universe the machine-to-machine execution gateway (POST /runtime/agents/:id/execute, via CarcRuntimeClient — see SDK Guide) authenticates against — structurally separate from every PrincipalCredential above; neither is ever accepted where the other is expected.

POST /admin/integration-environments/:id/credentials     # bind — raw_credential is write-only, never echoed back
GET  /admin/integration-environments/:id/credentials      # read the current binding (404 if none yet)
POST /admin/integration-credentials/:id/rotate            # credential_reference stays stable — only the underlying secret changes; zero inbound downtime
POST /admin/integration-credentials/:id/revoke            # terminal — deletes the underlying secret immediately

POST /runtime/integration-credentials/:id/rotate          # tenant-facing equivalent of rotate — "request allowed credential rotation"

At authorization time (IntegrationAuthorizationService), a request must satisfy — in order — an active tenant, a verified organization, an active non-expired integration and environment, an active non-expired credential binding matching the exact reference presented, an active registered agent with an active binding granting the requested capability, and a current, passed, non-expired certification for that environment. Any failure returns a stable lowercase error.code (e.g. integration_suspended, credential_not_bound, credential_revoked, certification_required) — never a generic 403 with no code.

Full worked example

services/runtime-control-engine/src/integrationLifecycle.e2e.test.ts (Milestone 2D) drives every step above — principal creation through production activation, successful and rejected runtime execution across both credential planes, suspension, rotation, revocation, and audit-trail reconstruction — against a real Postgres database and real HTTP routes. It's the most complete, guaranteed-current reference for the exact call sequence a real integration goes through.