SDK · BailingHub Docs

Available SDKs

PHP / PHP 7

Annotation or builder-based tool specs, tickets, tool call verification, callback verification, authz probes, and HubClient.

Node / Python

Builders for tool specs, tickets, HMAC verification helpers, authz probes, and HubClient.

Java / Go / .NET

Reference backend SDKs for enterprise stacks, implemented with standard libraries.

Any language

Publish OpenAPI with x-agent-capability ACC metadata and implement HMAC verification. No official SDK is required.

Install

GETPHP SDK package from your hub

curl -O {hub}/connect/bailing-connect-php.tgz
curl -O {hub}/connect/bailing-connect-php7.tgz

NPM@bailinghub/connect

npm install @bailinghub/connect

PIPbailing-connect

pip install bailing-connect

REFJava / Go / .NET

sdk/java
sdk/go
sdk/dotnet

Serve a protected or public spec with PHP / PHP 7

PHP 8+ and PHP 7.3+ expose the same SpecServer runtime API. The console exposes exactly two configurable policies, signed_required and public_allowed. New URL providers default to the former; select the latter only when catalog disclosure is intentional.

PHPBare PHP: choose one mode

use Bailing\Connect\SpecServer;

// Protected. Verifies the provider secret and emits private, no-store.
SpecServer::respond($spec, $toolProviderSecret);

// Explicitly public. Use instead of the line above with public_allowed.
SpecServer::respondPublic($spec);

PHPFramework route: preserve response headers

// Protected
[$status, $body] = SpecServer::handle(
    $spec, $toolProviderSecret, $method, $originalPathWithQuery, $requestHeaders
);
$responseHeaders = SpecServer::responseHeaders($toolProviderSecret);
// Apply every $responseHeaders entry to the framework response before sending it.

// Explicitly public; choose instead of the protected call above.
[$status, $body] = SpecServer::handlePublic(
    $spec, $method, $originalPathWithQuery, $requestHeaders
);

The older handle(..., null, ...) and respond(..., null, ...) forms remain compatible, but explicit public helpers keep intent visible in code. Existing older SDKs remain wire-compatible; after upgrading the hub, download the refreshed PHP package or at least add Cache-Control: private, no-store manually to protected responses.

Plain HTTP without the PHP SDK

Any language can serve a spec. A signed_required endpoint verifies the same sha256= HMAC used for tool calls. A spec fetch is GET, with an empty body, empty on-behalf-of subject, and empty job id.

GET/bailing/tools.json

X-Bailing-Timestamp: <unix-seconds>
X-Bailing-Signature: sha256=<hex-hmac-sha256>

canonical = "<ts>.GET.<path?query>.<sha256hex(empty-body)>.."
signature = "sha256=" + HMAC_SHA256(tool_provider_secret, canonical)

Request	Protected endpoint	Public endpoint
Validly signed GET	2xx with valid OpenAPI plus `Cache-Control: private, no-store`	2xx with valid OpenAPI
Unsigned GET	Prefer 401; 403 or 404 may hide the endpoint	2xx with valid OpenAPI
Invalidly signed GET	Prefer 401; 403 or 404 may hide the endpoint	Handle as a public request

New policies do not follow 3xx redirects, so configure the final URL. A request exceeding 10 seconds, a positive body over 5 MiB, an invalid spec, or inconclusive negative probes causes the hub to reject the refresh and preserve the old catalog.

Node example

JSTool spec builder

import { buildOpenApiSpec, param, tool } from '@bailinghub/connect';

export default buildOpenApiSpec({
  title: 'CRM Tools',
  version: '1.0.0',
  authzProbe: { method: 'POST', path: '/.well-known/bailing/authz-probe' },
  tools: [
    tool({
      name: 'member_query',
      method: 'GET',
      path: '/api/members/{id}',
      description: 'Query member profile',
      scope: 'member.read',
      requiresSubject: true,
      params: [param('id', { in: 'path', required: true, description: 'Member ID' })],
    }),
  ],
});

Common helper surface

Method names follow each language's style, but the capability surface is intentionally aligned.

Capability	PHP	Node	Python	Java / Go / .NET
Tool spec	annotations / builder	`buildOpenApiSpec`	`build_openapi_spec`	`BuildOpenApiSpec`
Visitor ticket	`Ticket::sign`	`signTicket`	`sign_ticket`	`SignTicket`
Tool call verification	`Verify::gate`	`verifyToolCall`	`verify_tool_call`	`VerifyToolCall`
Callback verification	`Verify::callback`	`verifyCallback`	`verify_callback`	`VerifyCallback`
Authz probe	`SpecServer::authzProbe`	`authzProbeResponse`	`authz_probe_response`	`AuthzProbeResponse`
Hub APIs	`HubClient`	`HubClient`	`HubClient`	`HubClient`

Verification rule

Every write-capable business tool should verify the hub signature, timestamp freshness, tool name, job id, and the on-behalf-of subject before applying business authorization. Signature verification proves the request came from the hub; business authorization still belongs to your backend.