BABCO LABS CONTROL PLANEDeveloper API and automatic connector contract
OpenAPI specification

DEVELOPER CONTRACT

Connect securely.
Report reliably.

Use the approved automatic connector whenever possible. It creates the approval request, receives the scoped credential as an encrypted envelope, reports usage, and retrieves official reconciliation.

Download connector ZIP Read the installation workflow Open approval workspace

PREFERRED INTEGRATION

Automatic connector

The approved Node connector generates an application-held RSA identity, signs the connection request, polls for administrator approval, decrypts the approved credential locally, and exposes usage and reconciliation methods.

Download the approved package: Babco Control Plane Automatic Connector v1.0.0. The ZIP contains no credentials. SHA-256: AEB759809AD89F9F27E8BBF23588F411B269A592940700851496697E5AFAC51C.
import { BabcoControlPlaneConnector } from "@babco/control-plane-connector";

const controlPlane = new BabcoControlPlaneConnector({
  displayName: "Example Application",
  slug: "example-application",
  environment: "production",
  requestedBy: "Example backend team",
  providerProjectId: process.env.OPENAI_PROJECT_ID,
  stateDirectory: process.env.BABCO_CONTROL_STATE_DIR
});

// Run in a non-blocking background startup task.
const status = await controlPlane.checkConnection();
console.log(status.status, status.verificationCode);
Persistent connector state is required. Store the generated private key, poll token, and encrypted envelope in a protected backend path that survives restarts and deployments. Never expose that path through HTTP or static files.

REPORT USAGE

Send one event after every OpenAI response

await controlPlane.reportUsage({
  occurredAt: new Date().toISOString(),
  provider: "openai",
  model: response.model,
  requestId: response.id,
  feature: "invoice-analysis",
  inputTokens: response.usage?.input_tokens ?? 0,
  cachedInputTokens: response.usage?.input_tokens_details?.cached_tokens ?? 0,
  outputTokens: response.usage?.output_tokens ?? 0,
  requestCount: 1,
  estimatedCostUsd: localEstimate,
  pricingVersion: localPricingVersion,
  status: "succeeded",
  metadata: { environment: "production" }
});

A telemetry failure must never fail a successful user operation. Use the application's durable queue or transactional outbox and suppress duplicates by provider request ID.

OFFICIAL RECONCILIATION

Retrieve only this application's summary

const summary = await controlPlane.getReconciliation({
  from: "2026-08-01T00:00:00Z",
  to: "2026-09-01T00:00:00Z"
});

console.log(summary.local);
console.log(summary.official);
console.log(summary.reconciliation);
console.log(summary.official.costUsd); // authoritative final cost
Underlying authenticated HTTP contract

The connector uses the following application-scoped endpoints after encrypted activation:

POST /api/v1/usage-events
X-Babco-Application-Id: <scoped application ID>
X-Babco-Control-Key: <decrypted in application memory>
Content-Type: application/json
GET /api/v1/applications/me/summary?from=...&to=...
X-Babco-Application-Id: <scoped application ID>
X-Babco-Control-Key: <decrypted in application memory>
Never place these values in browser JavaScript, source control, screenshots, tickets, or logs. The connector's encrypted envelope is the approved delivery mechanism.

OPERATIONAL RULES

Integration requirements

  1. Use one OpenAI project and one Control Plane application mapping per deployed environment.
  2. Run the connection check in a non-blocking background startup task.
  3. Persist connector state securely across restarts and deployments.
  4. Report usage from the backend after the provider response is received.
  5. Use the provider request ID for deduplication and investigation.
  6. Record failed and cancelled calls when tokens or cost may still have been consumed.
  7. Use official.costUsd as the authoritative final OpenAI cost.
  8. Never call OpenAI organization Usage, Costs, or Projects APIs from an application integration.