Connector fleet HTTP API

This reference describes the HTTP contracts used inside an AIP connector fleet. Use it to identify the correct process and route, construct a signed request, and interpret route, lease, replay, and capacity failures.

The contract applies to source revision 97be86e9efedf07ecf1783b03800f683f107fb04. It is an implementation boundary between trusted fleet components. It is not a public connector-catalog administration API and does not add fields to AIP 1.0.

Three HTTP planes

Each plane has its own signer and authorization checks. Bearer authentication for the public native API does not replace these signatures. Operational health, readiness, manifest, and metrics routes have no application authentication in their process routers; protect them at the deployment edge.

Connector-host data plane

One connector-host process exposes five routes:

The admitted public endpoint must be an absolute URL ending exactly in /aip/v1/messages, without credentials, query, or fragment. HTTPS is required except for explicitly enabled loopback development. The default request-body limit is 4 MiB.

Health and readiness

GET /health reports process liveness only:

{
  "status": "ok",
  "protocol": "AIP",
  "version": "1.0",
  "service": "aip-connector-host"
}

GET /ready returns HTTP 200 only when all four conditions are true:

• the host is not draining;
• its registry lease has not expired;
• durable runtime storage passes its probe; and
• the connector-specific health probe is ready.

Otherwise it returns HTTP 503. The body exposes status, lease_valid, draining, a runtime object with durability, readiness, detail, and recovery state, and a connector readiness object. Readiness does not prove that an external provider request succeeded.

Message authentication and route pinning

POST /aip/v1/messages accepts a complete AIP Envelope. Before dispatch, the host verifies all of these boundaries:

1. The JSON passes the Envelope schema and decodes successfully.
2. The Ed25519 envelope signature resolves to the configured central gateway DID.
3. from matches the configured gateway principal, kind, and trust domain.
4. to matches this host principal.
5. security.connector_route matches the admitted tenant, instance, replica, version, and manifest digest.
6. An action or cancellation matches the route’s action and capability.
7. Any credential revision and approval authorization remains valid locally.

The central dispatcher places these fields in security.connector_route:

The deployed remote dispatcher sends actions and action-scoped cancellations. It projects verified tenant identity into the action. An async client action is executed synchronously at the host hop because the central runtime owns durable queueing. A streaming action retains streaming mode and receives only the fixed central callback destination.

The host signs every post-decode success or protocol-error envelope with its configured host key. It also correlates the response to the request. The central dispatcher authenticates the endpoint and verifies the expected host principal, DID, and trust domain before accepting the response.

Host message errors

Schema and decode errors occur before a trustworthy request envelope exists, so those responses are unsigned input errors. Later errors are correlated and signed. Credential or approval-journal checks can add a more specific 403 or 503 error.

Host lifecycle control plane

The standalone connector control plane exposes:

GET /ready returns HTTP 200 with schema_version, catalog_revision, and pools only when the restricted registry connection is healthy and the installed schema is current. It returns 503 with schema_ok and catalog_ok otherwise. Unlike connector-host metrics, control-plane /metrics is a JSON pool snapshot, not Prometheus text.

Signed lifecycle request

The request body has a signed outer wrapper:

{
  "request": {
    "request_id": "msg_0190c42f2d5a70008000000000000001",
    "issued_at": "2026-07-26T12:00:00Z",
    "expires_at": "2026-07-26T12:00:30Z",
    "signer_did": "did:key:z6Mk...",
    "command": {
      "operation": "heartbeat",
      "payload": {
        "replica_id": "crepl_booking_region_a_one",
        "previous_sequence": 17,
        "in_flight": 3,
        "connector_ready": true
      }
    }
  },
  "signature": "base64-ed25519-signature"
}

signature is standard-base64 Ed25519 over canonical JSON for the request object. signer_did must equal the DID pre-provisioned for that replica. The control plane rejects an invalid signature, an unknown replica, or a signer that does not match the registry record.

The accepted clock window is deliberately small. The request lifetime cannot exceed 30 seconds, expires_at must be after issued_at and the current time, and issued_at can be at most five seconds in the future.

Lifecycle commands

Registration contains the complete proposed replica record plus manifest_digest, artifact_digest, tenant_id, config_revision, secret_provider_ref, and capability_count. The replica record carries its endpoint, peer principal and DID, trust domain, transport profile, topology, capacity, and initial health state. The control plane compares this proposal with the pre-admitted version, instance, and offline replica identity.

previous_sequence is a monotonic lease fence. A heartbeat cannot report more in-flight work than admitted capacity. connector_ready=false moves the replica offline instead of renewing it as ready. Drain stops new assignments while allowing already pinned work to finish.

Signed lifecycle response

Every normal or rejected operation returns a signed wrapper containing response and signature. The response repeats request_id, has its own 30-second issued_at and expires_at window, identifies the control-plane signer_did, and carries one outcome:

The host verifies the response request ID, trusted control-plane DID, time window, and signature before applying a lease. A response-signing failure is an unsigned HTTP 500 input-style error because no signed response can be produced.

The wrapper’s issued_at and expires_at fields are RFC 3339 strings. At this revision, ConnectorHostLease.expires_at uses the default time serialization instead: a nine-item array of year, ordinal day, hour, minute, second, nanosecond, and three UTC-offset components. Clients must not assume the lease field is also an RFC 3339 string.

Request IDs are replay protected. Retrying the exact signed bytes after a lost response is safe while that request remains the last committed lifecycle transition. Reusing the ID with different content, or replaying an older transition after a later state, is rejected.

The control endpoint must be an absolute HTTPS URL ending exactly in /aip/v1/connector-control, with no credentials, query, or fragment. Explicit loopback development may use HTTP. Request and response bodies are limited to 64 KiB.

Central connector ingress

Central aipd exposes two canonical connector-origin routes:

The connector host requires those exact paths when configuring its event and callback publishers. At this revision both routes mount the same shared handler, which selects behavior from the envelope body rather than the URL. Publishers should still use the canonical path for the body family.

Neither route uses native bearer middleware. The ingress validates the AIP envelope schema, exact central recipient, envelope signature, sender principal, registry state, tenant, version, manifest, attestation, and an active replica lease before storing content. Accepted responses are signed central envelopes correlated to the request.

Provider-event envelope

An event publisher sends a non-empty EventStream with no next_cursor and places these fields in security.connector_event:

The replica may be ready or draining, but its lease must remain current. The ingress binds each event actor to the signed host, writes verified tenant and connector provenance into event data, and then appends it to the durable event log. Reusing an event ID is accepted only when retained semantic content is equivalent; different content returns connector_event.idempotency_conflict.

Stream-callback envelope

A callback publisher sends one StreamChunk. Its security.connector_callback object contains the complete assigned route:

The chunk action ID must equal the route action ID. All durable assignment fields must match the central route resolver. The current replica must still match the assigned endpoint, identity, DID, trust domain, transport profile, instance, and version. A lease renewal may advance the live health revision, but it cannot invalidate the assignment’s other fences.

Ingress defaults and responses

Successful event ingress returns a signed EventStream containing the stored events. Successful stream ingress returns the signed EventStream produced by the central stream sink. The principal error cases are:

An error produced after envelope decoding is signed when the central ingress signer is available. Pre-decode and not-configured errors use the ordinary native error response.

Request-flow summary

Surface boundaries

This API does not expose catalog writes, connector admission, credential material, or registry database access to a connector host. Client-facing actions, queries, sessions, approvals, and audit routes remain in the native HTTP API. Complete deployment settings belong to connector-host configuration, and operational transitions belong to connector-host lifecycle.

Transport retry, destination, and response-authentication rules are detailed in transport bindings. Normative envelope and body definitions remain in JSON schemas.

Related documentation

• Deploy a connector fleet
• Errors and retry decisions
• Identity and trust