Build a private connector

A private connector is an org-owned connector provider backed by an adapter that the customer hosts. Voyant stores the provider manifest, grants, registrations, encrypted signing secret, and normalized connection state; the supplier adapter itself runs outside Voyant infrastructure. This model is for suppliers that are specific to one organization, such as an obscure bed bank, DMC, cruise consolidator, or airline GSA. The contractor building the integration owns the adapter service and exposes the protocol below. For protocol demos without building inventory, point metadata.externalAdapter.baseUrl at the public Voyant sandbox connector Worker and use HMAC as below — the sandbox implements the same operation paths.

Register the provider

CLI (recommended)

# Validate locally (optional --probe hits well-known manifest)
voyant connector validate ./connector.json --probe

# Register against your org (requires connect:providers:write)
voyant connector register ./connector.json --org <slug> --json

Store the one-time signingSecret from the register response in the adapter’s secret manager.

HTTP API

Register the provider with POST /connect/v1/connector-providers. The request body is the connector manifest. Private connectors must include metadata.externalAdapter; hostedWorker and externalAdapter are mutually exclusive. Registration validates the manifest, enforces public HTTPS URL policy on metadata.externalAdapter.baseUrl, and probes the adapter endpoint (well-known manifest preferred; otherwise /health must respond as reachable, including 401/403 when signature is required). For stays and packages, the well-known manifest’s operation list is recorded at registration. Declare quoteStay/quotePackage and lockStay/lockPackage only when those operations are implemented. A declared quote that returns null or fails stops the hold; an adapter without a declared quote can hold an unexpired search offer. Legacy adapters registered through the health fallback retain the quote dispatch path until they publish an operation list. After creation, PUT /connect/v1/connector-providers/{key}/manifest re-registers the manifest for the same provider — use it to update capabilities, credential forms, or the adapter target as the integration evolves. This PUT probes the new target again and replaces its admitted operation list. Connect also discovers operation lists through its pinned egress relay for providers registered before operation lists were recorded. Only the owning organization can touch an owned key, and platform-managed metadata (managedByOrganizationId, website, applicationForm, iconObjectKey) is ignored if a manifest tries to set it. Adapters may also self-describe by serving their manifest at /.well-known/voyant-connect/manifest, which is how hosted connectors publish theirs; for private connectors it is optional but useful for voyant-side validation tooling.

{
  "key": "local-supplier",
  "displayName": "Local Supplier",
  "description": "Private integration for Local Supplier inventory",
  "authModel": "bring_your_own_credentials",
  "accessModel": "credential_scoped",
  "categoryCoverage": ["hotel"],
  "supplyModel": "dynamic",
  "capabilities": ["catalog_read", "availability_read", "booking_create"],
  "supportsMarkets": true,
  "defaultMarkets": ["RO"],
  "supportedDirections": ["inbound"],
  "credentialForm": {
    "type": "fields",
    "fields": [
      {
        "key": "apiKey",
        "label": "API key",
        "type": "password",
        "required": true
      },
      {
        "key": "baseUrl",
        "label": "Supplier base URL",
        "type": "url",
        "required": true
      }
    ]
  },
  "metadata": {
    "externalAdapter": {
      "type": "external_adapter",
      "baseUrl": "https://adapter.example.com/connect",
      "protocolVersion": "2026-05-28"
    }
  }
}

The response includes data.provider and data.signingSecret. The signing secret is revealed once. Store it in the adapter service secret manager; later reads do not return it.

URL constraints

metadata.externalAdapter.baseUrl must be a public HTTPS URL. The control plane rejects URLs with credentials, query strings, or fragments, and rejects hosts that are local, internal, loopback, private, link-local, carrier-grade NAT, documentation-only, benchmark, multicast, reserved, or otherwise non-public after DNS resolution. Voyant repeats this policy at connect time in its connector egress relay. The relay resolves the complete DNS answer set, rejects the request if any answer is non-public, selects one accepted address, and pins that address into the TLS connection. It keeps the original hostname for certificate validation and SNI. DNS failure and mixed public/private answers fail closed. The relay does not follow redirects. The configuration-time check remains defense in depth. It is not the check that authorizes the connection, so changing DNS after registration cannot redirect a connector request to a private service. Valid:

https://adapter.example.com/connect

Invalid:

http://adapter.example.com
https://user:pass@adapter.example.com
https://adapter.example.com/connect?tenant=acme
https://localhost/connect

Request contract

Connect dispatches each operation with POST to:

${baseUrl}<operationPath>

If baseUrl is https://adapter.example.com/connect, searchStays is sent to https://adapter.example.com/connect/stays/search. The request body is JSON:

type ConnectorWorkerRequest<TInput = unknown> = {
  protocolVersion: "2026-05-28";
  operation: string;
  context: {
    connectionId: string;
    operatorId?: string | null;
    connection: Record<string, unknown>;
    credentials: Record<string, string>;
    marketContext?: {
      market: string | null;
      language: string | null;
      currency: string | null;
    };
    now?: string;
    requestId?: string;
    correlationId?: string;
    idempotencyKey?: string;
    environment?: "sandbox" | "production";
  };
  input: TInput;
};

Treat operatorId, marketContext, and now as absent-able: catalog-wide operations dispatch without an operator, and only per-call operations carry the tracing fields. Code the adapter against this exact shape rather than assuming every field is present. The adapter must return one of these JSON envelopes:

type ConnectorWorkerResponse<TData = unknown> =
  | { ok: true; data: TData }
  | {
      ok: false;
      error: {
        code?: string;
        message: string;
        details?: unknown;
      };
    };

Headers and signing

Every external adapter request includes:

Header	Value
`Content-Type`	`application/json`
`X-Voyant-Connect-Protocol`	The manifest’s `metadata.externalAdapter.protocolVersion`, or `2026-05-28`
`X-Voyant-Connect-Operation`	The operation name, such as `searchStays`
`X-Voyant-Connect-Connection`	The Connect connection id
`X-Voyant-Connect-Provider`	The provider key
`X-Voyant-Connector-Timestamp`	Unix timestamp in seconds
`X-Voyant-Connector-Signature`	`sha256=<hex hmac>`

The egress relay authentication header is platform-internal and is never sent to the adapter. The adapter-facing method, URL path, body, headers, timeout envelope, and response handling are unchanged by relaying. The signature is HMAC-SHA256 over this canonical string:

${timestamp}POST${url.pathname}${bodyText}

url.pathname includes any path prefix from baseUrl plus the operation path. It does not include scheme, host, query, or fragment. bodyText is the exact raw request body bytes decoded as text.

async function verifyVoyantConnectorRequest(
  request: Request,
  signingSecret: string,
): Promise<{ ok: true; bodyText: string } | { ok: false; status: number }> {
  const timestamp = request.headers.get("X-Voyant-Connector-Timestamp");
  const signature = request.headers.get("X-Voyant-Connector-Signature");
  if (!timestamp || !signature?.startsWith("sha256=")) {
    return { ok: false, status: 401 };
  }

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) {
    return { ok: false, status: 401 };
  }

  const bodyText = await request.text();
  const path = new URL(request.url).pathname;
  if (request.method !== "POST") {
    return { ok: false, status: 405 };
  }

  const canonical = `${timestamp}POST${path}${bodyText}`;
  const expected = await hmacSha256Hex(signingSecret, canonical);

  if (!timingSafeEqualHex(signature.slice("sha256=".length), expected)) {
    return { ok: false, status: 401 };
  }

  return { ok: true, bodyText };
}

async function hmacSha256Hex(secret: string, message: string): Promise<string> {
  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey(
    "raw",
    encoder.encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"],
  );
  const signature = await crypto.subtle.sign(
    "HMAC",
    key,
    encoder.encode(message),
  );
  return Array.from(new Uint8Array(signature))
    .map((byte) => byte.toString(16).padStart(2, "0"))
    .join("");
}

function timingSafeEqualHex(a: string, b: string): boolean {
  if (!/^[0-9a-f]+$/i.test(a) || !/^[0-9a-f]+$/i.test(b)) return false;
  if (a.length !== b.length) return false;

  let diff = 0;
  for (let i = 0; i < a.length; i += 1) {
    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
  }
  return diff === 0;
}

Operation paths

The platform dispatches only the operations it needs for a connection and the provider capabilities in use. Stay and package search offers carry __offerProof, which binds the exact offer snapshot, connection, and viewer to the hold request. Clients must preserve this field when posting offerId and offer to the lock route. Altered or expired offers require a new search. When releasing this hold validation, deploy the connector egress relay with restricted manifest GET support before deploying Connect API. Existing external adapters without recorded operations depend on that relay read to distinguish an absent optional quote from a failed configured quote. Before Connect API deployment, inventory active Stay and Package external registrations. Each must have an admitted operation list from registration or manifest update, or serve a valid well-known manifest through the relay. A health-only legacy registration without either source has unknown quote capability: update and probe its provider manifest with PUT /connect/v1/connector-providers/{key}/manifest before release. Do not treat a quote endpoint’s 404 as proof that quoting is optional; a failed declared or unknown quote must stop the hold.

Operation	Path
`validateCredentials`	`/validate-credentials`
`syncCatalog`	`/sync/catalog`
`syncPricing`	`/sync/pricing`
`searchStays`	`/stays/search`
`quoteStay`	`/stays/quote`
`lockStay`	`/stays/lock`
`confirmStay`	`/stays/confirm`
`cancelStay`	`/stays/cancel`
`getStayBooking`	`/stays/bookings/get`
`searchCruises`	`/cruises/search`
`quoteCruise`	`/cruises/quote`
`lockCruise`	`/cruises/lock`
`confirmCruise`	`/cruises/confirm`
`cancelCruise`	`/cruises/cancel`
`getCruiseBooking`	`/cruises/bookings/get`
`searchPackages`	`/packages/search`
`quotePackage`	`/packages/quote`
`lockPackage`	`/packages/lock`
`confirmPackage`	`/packages/confirm`
`cancelPackage`	`/packages/cancel`
`getPackageBooking`	`/packages/bookings/get`
`searchFlights`	`/flights/search`
`priceFlightOffer`	`/flights/price`
`bookFlight`	`/flights/book`
`getFlightOrder`	`/flights/orders/get`
`cancelFlightOrder`	`/flights/orders/cancel`
`ticketFlightOrder`	`/flights/orders/ticket`
`listFlightOrders`	`/flights/orders/list`
`getFlightSeatMap`	`/flights/seatmap`
`selectFlightSeats`	`/flights/seats/select`
`getFlightAncillaries`	`/flights/ancillaries`
`checkInFlight`	`/flights/checkin`
`modifyFlightOrder`	`/flights/orders/modify`
`refundFlightOrder`	`/flights/orders/refund`
`voidFlightOrder`	`/flights/orders/void`
`addFlightSsr`	`/flights/ssr`
`health`	`/health`

Rotate the signing secret

Use POST /connect/v1/connector-providers/:key/signing-secret/rotate to rotate the per-provider external adapter signing secret. The response includes the new data.signingSecret once, alongside the provider row. Deploy the adapter with the new secret before using it exclusively. The current dispatch code signs with the single encrypted secret stored on the provider row. Creating a private provider automatically creates an active owner self-grant. The owning organization can share the provider with another organization using:

POST /connect/v1/connector-providers/:key/grants
GET /connect/v1/connector-providers/:key/grants
PATCH /connect/v1/connector-providers/:key/grants/:granteeOrgId
DELETE /connect/v1/connector-providers/:key/grants/:granteeOrgId

Grant request and response payloads use camelCase. A grant can be active, suspended, or revoked, and may include expiresAt.

Lifecycle

Disable a private provider with:

PATCH /connect/v1/connector-providers/:key

{ "status": "disabled" }

Disable is a kill switch. The provider remains visible to the owner, but access checks deny usage while disabled. Delete a private provider with:

DELETE /connect/v1/connector-providers/:key

If active connections reference the provider, the API returns 409 with the active connection count. To tear down active references, revoke grants, remove provider registrations and stored provider secret material, and hard-delete the provider row, call:

DELETE /connect/v1/connector-providers/:key?force=true

Hard deletion frees the provider key for re-registration.

Reference implementation

The TUI connector is the reference implementation for the hosted connector protocol. It is registered as an internal provider with metadata.hostedWorker.type = "hosted_worker_target" and protocol version 2026-05-28, and the Connect API dispatches TUI stays and packages operations through the same operation envelope and response envelope described here.

​Register the provider

​CLI (recommended)

​HTTP API

​URL constraints

​Request contract

​Headers and signing

​Operation paths

​Rotate the signing secret

​Grants and sharing

​Lifecycle

​Reference implementation