Connector contract¶
Synchronized technical reference
This page is generated from docs/CONNECTOR_CONTRACT.md at the build commit. Use the portal navigation for setup guides and integration workflows.
What a connected application implements so the Hub can serve its data to AI clients. The application owns its records and its permissions. The Hub calls a small authenticated JSON API; it never introspects an ORM or a database.
Permissions managed by the application¶
An admin can choose connector_type: source_managed once when connecting a trusted
application. Its authenticated manifest must declare managed_by: application and
include only the models, operations and fields currently granted by that application's
admin. Each reviewed endpoint supplies a stable tool_key such as your_app.orders.list
and an optional safe description. Keys must belong to the manifest's application/module.
An explicitly empty modules: [] revokes all generated tools and is valid in this mode.
Before every authenticated MCP tool list and allowed call, the Hub fetches and validates this manifest, reconciles source policies and creates/updates/disables generated tools atomically. There is no separate enable/test/publish workflow per model. A failed or invalid policy fetch denies discovery/calls rather than using old grants. Sync calls only the manifest endpoint; it never reads business records or sends write requests.
Admin Apps, data-source and Tools lists also refresh authorized active source-managed connectors before reading their catalog. Removed/disabled grants are excluded from these lists and counts. Retired metadata remains available as history; it does not grant access. Failed refreshes return an error rather than displaying old grants as current.
The connected application remains responsible for record ownership, user status, current
permissions and any write confirmation. Hub privacy rules, fixed routes, signed delegation,
client write scope, allowlists and revocation still apply. Client keys cannot change mode,
register a different source or widen their scopes. Mode changes return the connector to
draft; test, discover and activate it once. Hub model/tool editing is locked in source mode.
Manual http_contract connectors retain their existing review and publication workflow.
Endpoints¶
| Method | Path | Purpose |
|---|---|---|
| GET | /api/ai/v1/health (configurable) |
Authenticated health. Body {"status": "ok"}. |
| GET | /api/ai/v1/capabilities (configurable) |
The capability manifest below. |
| as declared | each route in read_endpoints |
One reviewed read: GET, or POST marked safe_query: true. |
| as declared | each route in write_endpoints (optional) |
One reviewed create, update or delete request. |
Paths are relative to the base URL the admin enters. The Hub refuses redirects, private or metadata addresses (unless explicitly allowed for development), and any route that is not in the manifest.
Authentication¶
Every request carries the app's service credential as a bearer token:
Authorization: Bearer <token>. The Hub stores the token encrypted and never sends
X-API-Key; apps should reject requests without a matching bearer token. In Laravel,
$request->bearerToken() reads it.
A service credential proves the Hub may call the app. It does not prove which user is asking. For user-scoped routes:
- The app's AI gateway (or any trusted caller) sends
X-Hub-Delegationto the Hub with each MCP call. This is an HMAC-SHA256 token signed with the app's delegation secret:base64url(json) + "." + base64url(hmac), where the JSON is{"app_key", "tenant_id", "user_ref", "aud": "mcp-hub", "exp"}andexpis at most 150 seconds ahead (mint for 120 s or less). - The Hub verifies it, then sends the app
X-Hub-Assertion. This is a 60-second token signed with the same secret, withaudset to the connector's base URL and a randomjti. The Hub signs a new assertion for every HTTP attempt, retries included. - The app verifies the assertion, accepts each
jtionce (an atomic cache add untilexp, so a captured header cannot be replayed), and re-checks the user, tenant, permissions and records on every request.
Apps should also refuse plain HTTP in production and answer with Cache-Control: no-store
and X-Content-Type-Options: nosniff; the Laravel guide's middleware does both. Writes
should be denied by default: a model offers create, update or delete only when an explicit
rule (a policy) allows it.
Model-supplied arguments named user_id, tenant_id, role, approved, url, path,
method, token and similar are rejected and can never establish authorization.
Manifest¶
{
"contract_version": "1.0",
"application": "your_app",
"manifest_version": "2026-10-10.1",
"modules": [{
"key": "orders",
"name": "Orders",
"description": "Orders the signed-in user may see",
"schema_version": "1.0",
"supported_operations": ["read", "create"],
"readable_fields": ["ref", "status", "total", "created_at"],
"writable_fields": ["note"],
"field_policies": {"total": "aggregate_only"},
"max_page_size": 50,
"read_endpoints": [{
"method": "GET", "path_template": "/api/ai/v1/orders/list",
"requires_user_context": true, "tenant_field": "tenant_id",
"input_schema": {"type": "object", "additionalProperties": false, "properties": {
"status": {"type": "string", "enum": ["open", "paid", "void"]},
"limit": {"type": "integer", "minimum": 1, "maximum": 50},
"cursor": {"type": "string", "maxLength": 64}}},
"output_schema": {"type": "array", "maxItems": 50, "items": {"type": "object", "additionalProperties": false,
"required": ["ref", "status", "total", "created_at"],
"properties": {"ref": {"type": "string", "maxLength": 64},
"status": {"type": "string", "enum": ["open", "paid", "void"]},
"total": {"type": "number"},
"created_at": {"type": "string", "maxLength": 64}}}}
}],
"write_endpoints": [{
"operation": "create", "method": "POST", "path_template": "/api/ai/v1/orders/propose",
"requires_user_context": true, "tenant_field": "tenant_id",
"input_schema": {"type": "object", "additionalProperties": false, "required": ["note"],
"properties": {"note": {"type": "string", "maxLength": 200}}},
"output_schema": {"type": "array", "maxItems": 1, "items": {"type": "object", "additionalProperties": false,
"required": ["proposal_ref", "summary"],
"properties": {"proposal_ref": {"type": "string", "maxLength": 64}, "summary": {"type": "string", "maxLength": 300}}}}
}]
}]
}
Rules the Hub enforces when it syncs the manifest:
applicationequals the app key entered in the Hub. Module keys are lowercase identifiers.- Readable fields are an allowlist. Each field starts Visible to AI unless
field_policiessays otherwise (blocked,secure_form_only,aggregate_only). Names that indicate personal or secret data (email, phone, password, token, national id,user_id,tenant_id, …, including variants such asowner_emailorcontactPhone) are always blocked and locked. Admins can tighten a field, or relax it back to your declared level, never beyond. - Schemas are closed (
additionalProperties: false). Inputs are scalars with bounds or small string enums. Outputs are arrays of flat records with scalar (optionally nullable) fields that come fromreadable_fields. No$ref. - User-scoped routes set
requires_user_context: trueandtenant_field. Every returned row must contain the tenant field. The Hub drops rows for other tenants (and marks the answerpartial), then removes the field before anything reaches the AI. - Public routes (no user context) must say
"public_aggregate": trueand return only data that anyone with the client key may see. - Write routes are optional.
operationmust be insupported_operations; inputs must be declared readable or writable fields and never personal or secret data, including one-time and account codes (otp,pin,cvv,verification_code,card_number, …); user context is mandatory; the output is a small receipt. A write is enableable only when its route is declared. One refused input rejects the whole manifest, so the Hub keeps the app's tools hidden until the manifest is fixed: leave such fields out of write inputs. - Pagination: a list route that accepts
limit(integer) andcursor(string) and returnsmeta.has_more+meta.next_cursorcan be read page by page byrun_report.
A changed module is switched off in the Hub until an admin reviews it, and its tools need a new test. Unchanged modules keep working.
Responses¶
Reads:
{"success": true,
"data": [{"ref": "ord_1", "status": "paid", "total": 120.5, "created_at": "2026-10-01T09:00:00+08:00", "tenant_id": "t_1"}],
"meta": {"as_of": "2026-10-10T09:00:00+08:00", "timezone": "Asia/Makassar", "scope": "authorized_records",
"coverage": "complete", "total_count": 1, "has_more": false, "next_cursor": null}}
as_of is timezone-aware; timezone is an IANA name; coverage is complete or
partial. A page that is not the last one is partial with has_more: true. Never put
personal data in meta, cursors or error messages.
Write receipts use the same envelope. data holds one record with the declared receipt
fields plus the tenant field. meta.requires_confirmation: true tells the AI that nothing
changed yet and the user must confirm in your app. The Hub sends an Idempotency-Key
header with every write and never retries one.
Errors: {"success": false, "error": {"code": "PERMISSION_DENIED", "message": "Operation is not permitted"}}
with 401, 403, 404, 409, 422 or 429. The Hub forwards only the codes PERMISSION_DENIED,
VALIDATION_FAILED, NOT_FOUND, RATE_LIMITED and SCHEMA_MISMATCH; anything else
becomes UPSTREAM_ERROR.
Laravel sketch¶
The admin UI's Laravel guide (Docs → Laravel guide) builds the complete contract with a downloadable starter kit: list, get, prepare create/update/delete, proposals the user confirms, and a feature test for every path. The minimum read route looks like this:
// routes/api.php
Route::prefix('ai/v1')->middleware('hub.key')->group(function () {
Route::get('health', fn () => ['status' => 'ok']);
Route::get('capabilities', [HubController::class, 'manifest']);
Route::get('orders/list', [HubController::class, 'orders']);
});
// HubController::orders: the user comes from the verified assertion, never from input.
public function orders(Request $request)
{
$user = HubAssertion::verify($request->header('X-Hub-Assertion')); // HMAC, aud, exp, active user
abort_unless($user->can('orders.read'), 403);
$validated = $request->validate(['status' => 'in:open,paid,void', 'limit' => 'integer|min:1|max:50',
'cursor' => 'regex:/^page_\d{1,6}$/']);
$query = Order::whereBelongsTo($user)->when($validated['status'] ?? null, fn ($q, $s) => $q->where('status', $s));
$offset = (int) substr($validated['cursor'] ?? 'page_0', 5);
$limit = $validated['limit'] ?? 50;
$total = (clone $query)->count();
$rows = $query->orderByDesc('id')->skip($offset)->take($limit)->get(['id', 'status', 'total', 'created_at'])
->map(fn ($o) => ['ref' => 'ord_'.$o->id, 'status' => $o->status, 'total' => (float) $o->total,
'created_at' => $o->created_at->toAtomString(), 'tenant_id' => 'user_'.$user->id]);
$more = $offset + $rows->count() < $total;
return ['success' => true, 'data' => $rows, 'meta' => [
'as_of' => now()->toAtomString(), 'timezone' => config('app.timezone'), 'scope' => 'authorized_records',
'coverage' => $more ? 'partial' : 'complete', 'total_count' => $total, 'has_more' => $more,
'next_cursor' => $more ? 'page_'.($offset + $rows->count()) : null]];
}
Keep the field list explicit (never Model::all()), select only declared fields, and
compute aggregates at the source when individual values are sensitive.
The reference app implements the contract in Python, including a create route that only returns a proposal.