ObjectStackObjectStack

Connectors — call external systems safely

Call external systems from flows with plugin connectors or declarative rest, openapi and mcp instances — pure metadata with reference-based credentials.

Status: Shipped · Audience: App authors (human and AI), integration engineers

TL;DR — A connector packages an external system behind named actions that flows dispatch with the connector_action node. You get one in two ways: a plugin registers it from host code, or — since ADR-0097 — you declare it as pure metadata: a connectors: entry naming a provider (rest, openapi, or mcp) is materialized into a live connector at boot, no plugin code required. Credentials are references (credentialRef), never secrets inlined in metadata. This page is the authoring guide for that declarative path — what to write, how auth works, and how it fails.

A connector is a transport mechanism: it knows how to reach one external system and exposes that system as a set of dispatchable actions. The runtime keeps a connector registry — GET /api/v1/automation/connectors lists it, the Studio flow palette browses it, and a flow's connector_action node dispatches against it. Connectors are not messaging channels (ADR-0022): "send a Slack message" is a connector action; routing, templating, and user notification preferences live in the messaging layer.

The three shapes of a connectors: entry

ShapeBehavior comes fromWhen to use
Plugin-registered connectorHost code: a plugin calls engine.registerConnector(def, handlers) (brand connectors like Slack, or the executors' hand-wired instance options)The integration needs custom logic, or ships as an installable plugin
Provider-bound instance (ADR-0097)An installed generic executor (rest / openapi / mcp) materializes the entry at bootThe upstream is an HTTP API, an OpenAPI document, or an MCP server — declare it as metadata, write no code
Catalog descriptorNothing — the entry is inert documentationCataloguing a planned or externally-managed integration (below)

The first shape is code and belongs to plugin development. This guide is about the other two — the entries a tenant (or an AI author) writes into stack metadata.

Declaring a provider-bound instance

A declarative entry becomes a live connector the moment it names a provider:

import { defineConnector } from '@objectstack/spec/integration';

export const BillingApiConnector = defineConnector({
  name: 'billing_api',
  label: 'Billing API',
  type: 'api',
  provider: 'rest',
  providerConfig: {
    baseUrl: 'https://billing.example.com',
  },
  auth: { type: 'bearer', credentialRef: 'BILLING_API_TOKEN' },
});

Wire it into the stack alongside your other metadata:

// objectstack.config.ts
export default defineStack({
  // ...
  connectors: [BillingApiConnector],
});

At boot, the automation service resolves each provider-bound entry:

  1. Look up the provider factory registered under entry.provider. The three generic executors — @objectstack/connector-rest, @objectstack/connector-openapi, @objectstack/connector-mcp — each contribute one. A scaffolded project (npm create objectstack) lists none: install the provider's package and add its executor to plugins: when the app first declares a connector, beside the automation capability that performs the materialization. A plugin is code, so an app that lists one installs only as a managed package, never as an editable (unmanaged) copy.
  2. The factory validates providerConfig and the automation service resolves auth.credentialRef to its secret (see What credentialRef resolves through). A reference that is not set yet does not stop the boot: that one instance registers degraded until an administrator sets it.
  3. The result is registered on the connector registry — indistinguishable from a hand-written connector. Its actions are derived from the upstream (the OpenAPI document's operations, the MCP server's tools/list, the REST executor's generic request), never authored.

Three authoring rules are enforced when the stack is validated:

  • providerConfig and auth require provider — on an entry without one they are meaningless materialization inputs and are rejected.
  • A provider-bound instance must not inline secrets via authentication (the runtime auth shape) — see Authentication.
  • A provider-bound instance must not author actions or triggers — the provider derives actions from the upstream at boot; authoring both the instance and its actions would let them drift apart (ADR-0097 §5).

Provider config contracts

providerConfig is deliberately not validated by the stack schema — each provider factory validates its own config at boot (re-modelling an OpenAPI document or an MCP transport inside the stack schema is exactly what ADR-0023 rejected). A wrong or missing key is therefore not flagged by os validate; it surfaces as a hard boot error naming the connector. Check the contracts below against what you wrote.

provider: 'rest' — a generic HTTP client

Config: baseUrl (required, e.g. https://api.example.com) and defaultHeaders (optional string→string map merged into every request; request-level headers win).

Materializes a single request action accepting { method?, path?, headers?, query?, body? } — the flow supplies the path and payload per call. Use it when the upstream is "just HTTP" and you don't have a spec document.

Do not put a credential in headers or defaultHeaders: both are stored in metadata and served with it. Declare it as auth.credentialRef instead — the resolved auth is applied to every request — as the Authorization header, or for api-key as headerName (default X-API-Key) or the paramName query parameter.

provider: 'openapi' — one action per operation

Config: spec (required), baseUrl (optional — overrides the document's servers[0].url) and include (optional operation allowlist — only the listed operations become actions). The spec takes any of three forms:

  • an inline OpenAPI 3.x document object — no I/O at boot, the most deterministic form;
  • an http(s) URL, fetched at materialization;
  • a package-relative file path like './specs/billing-openapi.json', resolved against the directory containing objectstack.config.ts and confined to it — absolute and ..-escaping paths are rejected. os build reads the file and writes its JSON into dist/objectstack.json in place of the path, so an artifact installed into another runtime carries the document; a path that names no file, or no JSON object, fails the build.
import { defineConnector } from '@objectstack/spec/integration';

export const CrmApiConnector = defineConnector({
  name: 'crm_api',
  label: 'CRM API',
  type: 'api',
  provider: 'openapi',
  providerConfig: {
    spec: './specs/crm-openapi.json',
  },
  auth: { type: 'api-key', credentialRef: 'CRM_API_KEY', headerName: 'X-API-Key' },
});

Each operation becomes an action keyed by its operationId (or a method_path slug when the document omits one) — so getInvoice in the document is actionId: 'getInvoice' in your flow.

Each path, query and header parameter is sent by the style and explode its Parameter Object declares, or by the OpenAPI 3.x default for its location (form for query, simple for path and header). An object or array input is encoded the way the document asks — Stripe's created: { gte: 1700000000 } (deepObject) goes out as created[gte]=1700000000, and its expand: ['data.customer'] as expand[0]=data.customer (deepObject applied to an array: each index in its own brackets). A parameter whose style OpenAPI 3.x does not define for its location fails the boot naming the operation and parameter; leave the operation out of include to bring the rest up.

include takes those same action keys and has the same allowlist meaning as the mcp provider's include: list the operations the instance should expose and every other operation stays out — the way to bring up a large API (hundreds or thousands of operations) as the handful of actions your flows call. An operation without an operationId is named by its generated method_path key (delete /customers/{id} → delete_customers_id); one that has an operationId is named only by it. An entry the document does not carry — a typo, or an operation the upstream renamed or removed — fails the boot with an error naming the entry and listing the document's keys; it is never ignored.

providerConfig: {
  spec: './specs/crm-openapi.json',
  include: ['listCustomers', 'getCustomer', 'delete_customers_id'],
},

The document must be OpenAPI 3.x. A Swagger 2.0 document — or one with no openapi version field — is refused at boot with an error naming the inline document, URL or file it came from: convert it to OpenAPI 3.x offline and point spec at the converted document. The runtime never converts.

The ObjectStack repository carries that offline step as a script (it is not shipped in the npm package): normalize-openapi reads a file or URL, JSON or YAML, converts Swagger 2.0 to OpenAPI 3.0, bundles and inlines every $ref, makes servers[0].url absolute, writes one JSON document and prints its sha256 — and, given allow-patterns, the include list for the operations they match.

pnpm --filter @objectstack/connector-openapi normalize-openapi \
  --in https://example.com/openapi.yaml --out ./specs/crm-openapi.json \
  --include-pattern '^GET /v1/customers' --trim

With --trim the document it writes holds only the operations the patterns match: every other operation, every path item left with none, and webhooks are dropped before inlining, so nothing reachable only from a dropped operation is written, and the printed sha256 is the hash of those trimmed bytes. Package that output — a large vendor document shrinks to the operations the app calls (Stripe's 612 operations, 63 MB at the default depth, become about 1.9 MB for six). Without --trim the whole document is written and the patterns only compute include, so include can be widened later by editing config alone; with it, widening means re-running the script. --trim without an --include-pattern is refused.

Inlining is bounded: a recursive schema, or one more than --max-depth (default 2) named schemas deep, becomes a typed stub whose description names the reference it replaced. A Swagger 2.0 operation whose empty consumes list would drop its request body is refused until --empty-consumes <media type> says which media type it accepts.

provider: 'mcp' — one action per tool

Config: transport (required), include (optional tool-name allowlist — only the listed tools become actions) and toolsSnapshot (optional per-tool pin, below):

  • { kind: 'http', url, headers? } — a remote MCP server over streamable HTTP. Resolved auth is folded into the request headers; a grant-bearing auth (oauth2, app-credential) is asked for on every request instead (see Grant-bearing kinds below).
  • { kind: 'stdio', command, args?, env?, credentialEnv? } — a local child process, policy-gated (below). Resolved auth is handed to the server in its environment, under the variable credentialEnv names (see A stdio server's credential below).
import { defineConnector } from '@objectstack/spec/integration';

export const SearchToolsConnector = defineConnector({
  name: 'search_tools',
  label: 'Search Tools (MCP)',
  type: 'api',
  provider: 'mcp',
  providerConfig: {
    transport: { kind: 'http', url: 'https://mcp.example.com/mcp' },
    include: ['web_search', 'fetch_page'],
  },
  auth: { type: 'bearer', credentialRef: 'SEARCH_MCP_TOKEN' },
});

At materialization the provider connects, calls tools/list, and maps each tool to an action — the MCP server's tool names are your actionIds. A paginated tool list is followed through every page (nextCursor), up to 100 pages; a server still paging after that fails discovery instead of yielding a truncated tool list. A server that is unreachable or failing degrades the instance, which is retried. A credential the server rejects (HTTP 401 / 403 on connect, handshake or tools/list) is a configuration fault instead: the instance is degraded naming the refusal, as described under A credential the upstream refuses below.

include has the same allowlist meaning as the openapi provider's: list the tools the instance should expose and every other tool stays out — the way to keep a destructive tool away from your flows and agents. It must be an array of tool names; any other shape (a string such as include: 'web_search', an object) fails the boot before connecting, and never falls back to exposing every tool. An entry the server's tools/list does not carry — a typo, or a tool the server renamed or dropped — is never ignored: the refusal names the entry and lists the server's tools. On an instance that sends no static credential — no auth, an api-key sent as a query parameter, a stdio transport, or a grant-bearing oauth2 / app-credential instance, whose token is borrowed per request — it fails the boot. When the instance sends a static auth credential (bearer, basic, or an api-key header), the entry may instead be a tool the server hides from that credential: some servers list only the tools a credential is allowed to use (GitHub's hides each tool a classic token's scopes do not cover), and the answer does not say what it hid. That instance is degraded as a credential the upstream refuses (below), never failing the boot, and its reason names both causes: a credential without the scopes those tools need, or a declaration naming a tool the server does not have. Leave include out to expose every tool.

Pinning tools: toolsSnapshot

include decides which tools an instance exposes; it cannot tell you when the server rewrites one of them — a new description that steers an agent, or an inputSchema that asks for more than it did. toolsSnapshot pins each tool you depend on: a record of tool name → the sha256 of that tool's definition. It is keyed by tool name, like include, and the two compose.

import { defineConnector } from '@objectstack/spec/integration';

export const PinnedSearchConnector = defineConnector({
  name: 'pinned_search',
  label: 'Pinned Search (MCP)',
  type: 'api',
  provider: 'mcp',
  providerConfig: {
    transport: { kind: 'http', url: 'https://mcp.example.com/mcp' },
    include: ['web_search', 'fetch_page'],
    toolsSnapshot: {
      web_search: '08171ae4ba3e1cc962cad9723c755a62c0785d8ecc241a66f08864184366a990',
      fetch_page: 'e8478992ffab43667be21a009ae297e3b4e36c7e9b2d3eb26b2ce307fef9cc78',
    },
  },
});

A tool's digest is the sha256, in lowercase hex, of the UTF-8 canonical JSON of { name, description, inputSchema } taken from its tools/list entry; a member the server does not send is left out (it is not hashed as null), and no other member (outputSchema, annotations) is hashed. Canonical JSON is: object members sorted by key in UTF-16 code-unit order (JavaScript's default string sort), at every depth; array elements in their order; strings, numbers, booleans and null written exactly as JSON.stringify writes them; no whitespace. For values read from JSON that is the RFC 8785 (JCS) form, so any JCS implementation reproduces it. In code, computeMcpToolsSnapshot(tools) from @objectstack/connector-mcp builds the record from a tool list with the same function the check uses.

On every materialization each pinned tool is hashed and compared on its own:

  • Every pinned tool served with its pinned definition — the instance materializes as usual.
  • A pinned tool served with a different description or inputSchema, or no longer served at all — the instance registers degraded and exposes none of its tools. Its reason names each such tool, with the digest the server now serves, and the logs say the pin did not match (the provider throws CONNECTOR_UPSTREAM_CHANGED, not the unreachable-server marker). The instance is re-checked on the retry backoff, so a server that serves the pinned definitions again recovers it on its own; to accept the change, review it and set the pin to the served digest (the edit re-materializes the instance at once). This holds for a pinned tool include also lists: once pinned, a tool the server stops serving is reported by the pin, not as an include typo. When the instance's own credential reached the server (its auth over http), a pinned tool the server does not list may be one hidden from that credential, so it is degraded as a credential the upstream refuses instead, naming both causes — a served tool that hashes differently is still reported by the pin.
  • A tool the pin does not name is not checked. Pin every tool you depend on, and keep tools the server adds out with include.

A toolsSnapshot that is not a record of tool name → 64 lowercase hex characters fails the boot before connecting, and so does a pinned tool that include leaves out — the instance never exposes it, so its pin would never be checked.

A stdio server's credential

A stdio MCP server reads its credential from an environment variable, and the value stays out of metadata the way an http server's does: declare auth with a credentialRef, and name the variable in transport.credentialEnv. The platform resolves the reference like any instance's (the environment, then a credential set under Setup → Connector credentials, then the host's resolver) and the provider hands the resolved secret to the child in that variable — the token of a bearer, the key of an api-key, the password of a basic (whose username, not a secret, goes in env if the server reads it).

import { defineConnector } from '@objectstack/spec/integration';

export const RepoToolsConnector = defineConnector({
  name: 'repo_tools',
  label: 'Repository Tools (MCP, stdio)',
  type: 'api',
  provider: 'mcp',
  providerConfig: {
    transport: {
      kind: 'stdio',
      command: 'repo-mcp-server',
      env: { LOG_LEVEL: 'info' },
      credentialEnv: 'REPO_MCP_TOKEN',
    },
  },
  auth: { type: 'bearer', credentialRef: 'REPO_MCP_TOKEN' },
});

The value is never stored, logged, served on a metadata read (which shows credentialRef and credentialEnv, two names) or carried in a message; it exists only in the environment the server is started with. A reference that resolves to nothing never starts the server: the instance is degraded naming the reference, and a credential set later starts it. These fail the boot: a credentialEnv that is not a variable name, one on an http transport, one with no bearer / api-key / basic auth to place, and one naming a variable env also sets. A stdio transport that names no credentialEnv does not apply auth. A literal credential typed into env instead is reported by the connector-credential-literal advisory, which points here.

Declarative stdio transports are denied by default. Materializing one spawns a local process from metadata — which a runtime Studio publish can introduce — so anyone who can publish metadata could otherwise execute commands on the server. The host opts in per command:

new ConnectorMcpPlugin({ declarativeStdio: ['node'] })  // exact-match allowlist

The boot error you hit without the opt-in spells out this exact fix. The allowlist is a deliberately coarse boundary — allowlisting a launcher like npx effectively trusts anything it can run, so list the specific server binaries you trust. Hand-wired MCP connectors configured in host code are not subject to this policy (their command is host code), and http transports need no opt-in.

Authentication

Connector auth answers "how do we authenticate to the external system" — it is unrelated to how users authenticate to ObjectStack. There are two shapes, and which one you write depends on which of the two connector worlds you are in:

Declarative instances: references, never secrets

Stack metadata is authored, versioned, and shipped — a raw token must never live in it (ADR-0097 §3). The auth field on a provider-bound instance therefore has no field that can hold a secret. Its secret-bearing variants carry a credentialRef instead, resolved at materialization:

auth: { type: 'none' }                                     // public upstream
auth: { type: 'bearer', credentialRef: 'BILLING_API_TOKEN' }
auth: { type: 'api-key', credentialRef: 'CRM_API_KEY',
        headerName: 'X-API-Key' }                          // or paramName: 'api_key'
auth: { type: 'basic', username: 'svc_objectstack',        // username is not a secret
        credentialRef: 'ERP_SVC_PASSWORD' }                // the password is

Variant notes:

  • api-key — the key travels in a header (headerName, default X-API-Key) or a query parameter (paramName); set one or the other.
  • basic — the username stays in metadata (it is not a secret); only the password resolves through credentialRef.

What credentialRef resolves through

The metadata author names a credential; the administrator who installs the app holds it. The automation service asks three sources, in order, and the first that answers wins:

  1. An environment variable of the same name on the server (BILLING_API_TOKEN above means process.env.BILLING_API_TOKEN). A self-hosted operator keeps this path, and it always wins.
  2. The connector credential store, sys_connector_credential: one row per reference, its value encrypted at rest by the host's crypto provider and masked on every read. An administrator fills it through the API below, with no access to the server environment, which is the hosted case.
  3. The host's resolver, when it injects one (AutomationServicePluginOptions.credentialResolver, such as a vault or KMS client). You author the same entry either way: it still just names a ref.

A reference no source answers for does not fail the boot. An app installs first and gets its credentials after, so that one instance registers degraded: it is listed on GET /api/v1/automation/connectors with a reason that names the reference, and a dispatch to it fails with the same reason.

Setting a credential

In the Console, an administrator sets them in Setup → Integrations → Connector Credentials. The page lists every reference with its status, the connectors that name it, and when it last changed. Each writable reference has a masked input that starts empty, whatever is stored: typing a value and saving stores it, and leaving the input empty keeps the current one. A reference with a value stored here also has Clear. One that an environment variable supplies is read-only, since the variable wins, and a rejected one shows the upstream's reason. Where the routes below refuse (a multi-organization environment, or a server without them), the page shows the server's sentence instead of a list.

Installing an app from the marketplace ends on the same inputs: once the install lands, the credentials its connectors still need are listed, each with Skip for now. A skipped one leaves its connectors degraded until it is set on the Setup page. The step comes after the install, not before it, because the routes below refuse a reference that no installed app declares.

Over the API, three routes, each requiring the manage_metadata capability:

GET    /api/v1/automation/connectors/credential-refs
PUT    /api/v1/automation/connectors/credential-refs/BILLING_API_TOKEN   { "value": "…" }
DELETE /api/v1/automation/connectors/credential-refs/BILLING_API_TOKEN
  • GET lists every reference an installed connector names, plus every stored one that nothing names any more. Each entry has a status (set, missing or rejected), a source (env, object, vault or null), whether this door can write it, and the instances naming it with their state. A stored one also says when and by whom it was last set (updatedAt, updatedBy) and when it was last seen working (lastVerifiedAt). It never includes a value.
  • PUT stores the value, then reconciles. Every instance naming the reference re-materializes with it without a restart, and the answer is the reference's entry after that. The route refuses, before writing anything: a reference no installed connector declares (404), one an environment variable already supplies (409, because the variable wins and a stored value would never be read), an empty value, and a value starting with secret: (400: the store would read it as a handle to another stored secret). With no crypto provider it answers 503, since a credential is only ever stored encrypted. Writes on one server run one at a time, each with its reconcile, so the instances always end on the value the store ends on.
  • DELETE removes the stored value. The instances naming the reference are torn down and registered degraded again.

Installing a package reports the same facts for it: the install-local answer (POST /api/v1/marketplace/install-local, which os package install calls) lists the credentialRefs the package's connectors name, each with its status, plus a credentialNote naming the ones still to set.

A credential the upstream refuses (HTTP 401 / 403) degrades the instance, with a reason quoting the upstream's message, never the value. An mcp instance finds this out when it connects, and treats a server that accepts the credential but does not list a tool its include names the same way. A rest or openapi instance finds out on the first call answering 401 / 403; that call returns its answer as usual, and the instance is degraded after it. What happens next depends on where the value came from:

  • A value stored here is marked rejected, and its instance is not retried until the credential is set again, its declaration changes, or the server restarts. The mark outlives a restart: it clears only when the value is set again or an mcp handshake that carries it succeeds. A rest / openapi call answered 2xx does not clear it, because the endpoint may not check the credential at all.
  • A value from an environment variable or the host's resolver can change where this door cannot see it (a rotation, or a 403 rate limit that lifts), so its instance is retried on the same 5s→5min backoff as an unreachable upstream. The listing reports it rejected until an mcp handshake proves it or the server restarts, even while the instance is serving again.

Credentials are environment-level: one value per reference for the whole environment, read by whichever instance names it. On a multi-organization environment (the group or isolated tenancy posture) the store is not used at all. The three routes refuse with a message naming the posture, and a reference resolves from the environment variable or the host's resolver only, so a row stored before the posture changed is not read.

The same resolver serves an api flow's start-node config.secretRef, the name of its inbound hook secret. That one goes through the injected resolver alone (environment variables by default) and is read at every post rather than at boot, so a name with no value refuses each post with 503 (Flows).

Inlining a secret is rejected when the stack is validated. Writing the runtime shape on a provider-bound instance —

// ✗ rejected at authoring/publish:
//   "must not inline secrets via `authentication`; reference credentials
//    with `auth: { type, credentialRef }` instead (ADR-0097 §3)."
authentication: { type: 'bearer', token: 'sk_live_9f…' },

// ✓ a reference, resolved at materialization (unset, it degrades the instance):
auth: { type: 'bearer', credentialRef: 'BILLING_API_TOKEN' },

— fails validation, and auth: { type: 'bearer', token: … } is not even a legal shape (the declarative union has no token field to put a secret in).

Grant-bearing kinds: oauth2 and app-credential

Some upstreams take no static credential: the token is obtained from a token endpoint and refreshed as it expires. Two more auth kinds declare that, in the open tier (ADR-0143). They are grant-bearing: the metadata carries the endpoints, the client id and a credentialRef for the client or app secret, never a token. Access and refresh tokens are runtime state and have no key here.

// OAuth 2.0 — a user grants access once (`authorization_code`, PKCE S256 always on):
auth: {
  type: 'oauth2',
  grant: 'authorization_code',
  authorizationUrl: 'https://vendor.example.com/oauth/authorize',
  tokenUrl: 'https://vendor.example.com/oauth/token',
  scopes: ['crm.read'],
  clientId: 'objectstack-prod',
  credentialRef: 'VENDOR_CLIENT_SECRET',   // omit for a public client
}

// OAuth 2.0 — server to server (`client_credentials`, a confidential client):
auth: {
  type: 'oauth2',
  grant: 'client_credentials',
  tokenUrl: 'https://vendor.example.com/oauth/token',
  resource: 'https://api.vendor.example.com',
  clientId: 'objectstack-prod',
  credentialRef: 'VENDOR_CLIENT_SECRET',   // required for this grant
}

// A vendor app credential (Feishu, DingTalk, WeCom): app id + app secret → tenant token
auth: { type: 'app-credential', vendor: 'feishu', appId: 'cli_a1b2', credentialRef: 'FEISHU_APP_SECRET' }

What the publish door checks, each refusal located at its key under auth:

  • oauth2 needs tokenUrl and clientId, plus authorizationUrl on authorization_code. The one exception is provider: 'mcp' over an http transport, which may omit the endpoints and the client id: the MCP authorization flow discovers the server's metadata and can register the client. An authorization_code instance may instead declare clientSource: 'installer' and name no clientId and no credentialRef: the administrator of each deployment registers their own client with the vendor and enters it when they connect (below); a clientId beside it is refused. client_credentials has no authorization step, so authorizationUrl is refused there, and it requires credentialRef. A credentialRef without its clientId is refused. An inline clientSecret, refreshToken or accessToken is refused by name, pointing at credentialRef. There is no PKCE switch.
  • app-credential takes vendor (feishu, dingtalk or wecom), appId and a required credentialRef. An inline appSecret is refused by name.

How the server serves them. Both kinds are served through a credential handle the provider asks on every request. The built-in rest, openapi and mcp providers ask it; a provider says it does by registering with registerConnectorProvider(…, { credentialHandle: true }). For an openapi instance the document's security decides only where the token is not sent: an operation whose effective security is [] is anonymous and never carries it, and a header or query parameter an apiKey scheme names is the platform's to fill, so it is left out of the action's input schema, as Authorization is.

An mcp instance carries a grant-bearing credential only over an http transport (a stdio server is handed a static credential once, at spawn, in transport.credentialEnv; a handle on a stdio transport, or beside a static credential, fails the boot). Every HTTP request of its MCP session asks the handle. Each organization a dispatch runs for opens its own session with its own token, so organizations never share one. The tools are listed at materialization, outside any run, so the listing names no organization: on an authorization_code instance it uses the connection connected earliest (connected_at, ties by organization id), so an instance several organizations connected still lists. When that connection is revoked, refused or connected again, the instance materializes again and lists with the next one. A dispatch whose run names no organization is answered as below: from the only connection, refused when there are several.

An app-credential instance runs its vendor's exchange from the appId and the app secret its credentialRef names. The exchange is fixed per vendor, and nothing about it is authored:

vendorToken requestWhere the token rides on a call
feishuPOST https://accounts.feishu.cn/oauth/v3/token (client_credentials)Authorization: Bearer
dingtalkPOST https://api.dingtalk.com/v1.0/oauth2/accessTokenheader x-acs-dingtalk-access-token
wecomGET https://qyapi.weixin.qq.com/cgi-bin/gettokenquery parameter access_token

The token belongs to the app, so a run's organization selects nothing, and there is nothing to connect. It is kept in memory only, never stored (the app secret re-derives it at any time), and obtained afresh when it is within 30 seconds of its expiry, or once when the upstream answers 401. Concurrent requests share one exchange. WeCom can invalidate a token before it expires and says so inside an ordinary answer (errcode 40014 or 42001) rather than with a 401: such an answer obtains the token afresh once and repeats the call once, and a second such answer fails the call. No exchange follows a redirect. An exchange that gets no answer, a 429 or a 5xx fails the dispatch CONNECTOR_UPSTREAM_UNAVAILABLE, retried on the existing backoff; a vendor that refuses the app id or secret fails it with 503, naming the instance and at most the vendor's error code, never the vendor's text.

An oauth2 instance's access token is obtained from tokenUrl (the client authenticating with HTTP Basic, or by client_id alone as a public client), cached in memory only, refreshed when it is within 30 seconds of its expiry, and refreshed once more, with one retry, when the upstream answers 401. Concurrent requests share one token request, and with a cluster service a refresh runs under the cluster lock, so a rotating refresh token is never spent twice.

  • client_credentials needs nothing more: the client secret its credentialRef names re-derives the token at any time.

  • authorization_code needs an administrator to connect it, once per organization. Until then the instance is degraded "not connected" (never a failed boot). The connect is three calls, each needing the organization-scoped manage_connector_connections capability. Platform administrators and organization administrators hold it by default, so an organization's owners and admins can connect its vendors from the start; grant it to anyone else through a permission set. Connecting and revoking is a human administrator's act, taken from a signed-in session: an agent acting for them (an OAuth client) or an API key is refused by name, whatever it holds.

    GET  /api/v1/automation/connectors/:name/connection     → { status, …, redirectUri }
    POST /api/v1/automation/connectors/:name/connection     → { authorizationUrl, expiresAt }
    GET  /api/v1/automation/connectors/oauth/callback?code=…&state=…   (the vendor redirects here)
    DELETE /api/v1/automation/connectors/:name/connection   → revoke

    An instance declaring clientSource: 'installer' takes its client in the connect's body, { "clientId": "…", "clientSecret": "…" } (omit clientSecret for a public client). Register that client with the vendor first, with the redirect URI <origin>/api/v1/automation/connectors/oauth/callback: the status read answers that exact URI as redirectUri before any client exists. That is the one place a client, the Console included, reads it from, never the browser's own origin (wrong behind a proxy, or when OS_AUTH_URL / OS_BASE_URL name another origin). The authorization request, the code exchange and every refresh of that organization's connection then go out as that client. A reconnect keeps the stored client unless it brings a new one: a connect that names no client reuses the one the organization's connection keeps (the secret is never read back, so it need not be entered again), and one that names a client replaces it. The connection keeps it encrypted; the status read shows client: { source: 'installer', clientId, hasSecret }, never the secret. A first connect of such an instance without a client (or one after a revoke, which removes the kept client), a client offered to any other instance, and any other body key are refused 400 VALIDATION_ERROR.

    In the Console, Setup → Integrations → Connector Connections drives these calls; the entry is shown to holders of manage_connector_connections. It lists each authorization_code instance with the organization's status, the reason the server recorded and, for a degraded instance, the server's reason beside the connection that caused it. Connect and Reconnect open the vendor's sign-in in its own window, detached from the page, and the page shows the new status once the callback has stored it; Disconnect revokes after a confirmation.

    GET …/:name/connection answers the organization's status (not_connected, connected, reconnect_required), never a token, and, whatever the status, redirectUri: the deployment's redirect URI to register with the vendor. It is absent when the deployment has no base to derive it from (the read still answers; a connect is then refused 503), never guessed from the request. The state and the PKCE verifier are bound to the user and organization that began the connect and are used once; a callback from anyone else is refused before its code is exchanged. While the connect waits (ten minutes at most) it is held in the cluster KV, or in process on a single node, sealed under a key derived from the state itself, which the server never stores: the KV holds only the state's digest and an AES-256-GCM envelope, so a party that can read the KV learns no verifier, user or organization, and a value edited or moved there opens as nothing and its code is never exchanged. Write access to the cluster KV stays inside the platform's trust boundary, as it is for the cluster lock: such a writer can still delete a waiting connect. On an mcp instance over http that leaves its endpoints or its client to discovery, the connect runs the MCP authorization flow: the server reads the MCP server's protected-resource metadata (RFC 9728), then its authorization server's metadata (RFC 8414, or OpenID Connect discovery). That metadata's issuer must be the one the MCP server named, and S256 must be listed. A declared clientId is used as is; otherwise a public client is registered (RFC 7591) for the deployment's redirect URI, and an authorization server with no registration endpoint is refused, naming the clientId to declare. Every authorization and token request carries the MCP server's resource indicator (RFC 8707), and a callback that names another issuer is refused before its code is exchanged (RFC 9207). Every URL on the way must be https:// (plain http:// only to a loopback host), and no request follows a redirect. An MCP or authorization server that does not answer (or answers 429 / 5xx) refuses the connect with 503; metadata that is missing or fails a check above, with 400. The discovered endpoints and client, including any client secret the registration issued, are kept encrypted in the connection's registered_client; refreshes use them, and a reconnect reuses them instead of registering again. The redirect URI is the deployment's (OS_BASE_URL or OS_AUTH_URL plus /api/v1/automation/connectors/oauth/callback, or the automation plugin's connectorOAuthRedirectUri), never the request's; register that URI with the vendor. The refresh token is kept encrypted in sys_connector_connection, one row per organization and instance, an instance being its package and name (one per organization for an instance the environment authored or a plugin registers); it is not a sign-in account, and signing in never touches it. A callback completes the instance its connect was begun for, never the name read again, and the bare connect door refuses with 409 a name two packages hold rather than pick one: connect each package's instance at its namespace address, /api/v1/automation/connectors/NS/NAME/connection (see Two packages, one connector name). A run dispatches with its own organization's connection; a run with no organization uses the instance's only connection, and is refused when there are several. When the grant stops working, the connection is marked reconnect required and the instance degraded until an administrator connects it again. That happens when the vendor refuses the grant on refresh (invalid_grant), when the connection keeps nothing to renew an access token it has to renew with (the vendor issued no refresh token, or no client is kept to refresh with), or when the upstream refuses the connection's token while an mcp instance discovers its tools. The connection's statusReason says which. A refresh, and the mark "reconnect required", are each written only over the revision they read, in one conditional write, so a stale one never overwrites a newer connect on any replica. A revoke deletes the stored connection only: the server does not revoke the refresh token at the vendor (RFC 7009), because no revocation endpoint is known for the instance — the auth declares none, and the MCP authorization flow does not read one. The refresh token stays valid at the vendor until it expires or is revoked in the vendor's console; revoke it there too when the disconnect is a response to a leak.

What is not served yet is held degraded with a reason that names it, and never called without its credential: an oauth2 or app-credential instance on a provider that does not ask the credential handle (a plugin's provider registered without { credentialHandle: true }), an oauth2 instance without its endpoints or client that the MCP authorization flow cannot discover them for (only an authorization_code instance on provider: 'mcp' over an http transport does), an mcp instance left to discovery whose transport url is not https://, and an oauth2 instance whose tokenUrl or authorizationUrl is not https:// (plain http:// is accepted only to localhost, a 127.0.0.0/8 address or [::1] — not a *.localhost name, which the system resolver sends to DNS — so the client secret and the refresh token never cross a network in the clear; a token endpoint that answers with a redirect is refused rather than followed). A datasource that borrows from a grant-bearing instance (external.connector) is refused with 422. Until then, declare a static kind (bearer, api-key or basic) to dispatch now; don't emulate a grant by putting a short-lived access token behind a bearer ref.

Request signing: signed

Some upstreams take no token at all: every request carries a signature over its own method, path, query, headers and body, computed with a key the caller never sends. The signed kind declares that (ADR-0143 D2.3). The metadata names the scheme and the public key id; the signing key itself is a credentialRef, resolved through the same chain as every other kind. A scheme whose vendor signs its responses also names the vendor's public key, as a second reference.

// Alibaba Cloud OpenAPI, V3 signature (ACS3-HMAC-SHA256):
auth: {
  type: 'signed',
  scheme: 'aliyun-acs3-hmac-sha256',
  keyId: 'YourAccessKeyId',               // the AccessKey ID: public, stays in metadata
  credentialRef: 'ALIYUN_ACCESS_KEY_SECRET',
}

// Tencent Cloud API 3.0, signature v3 (TC3-HMAC-SHA256):
auth: {
  type: 'signed',
  scheme: 'tencentcloud-tc3-hmac-sha256',
  keyId: 'YourSecretId',                  // the SecretId: public, stays in metadata
  credentialRef: 'TENCENT_SECRET_KEY',
}

// Alipay OpenAPI v3 (ALIPAY-SHA256withRSA), responses verified:
auth: {
  type: 'signed',
  scheme: 'alipay-v3',
  keyId: '2021000000000000',              // the app id: public, stays in metadata
  credentialRef: 'ALIPAY_APP_PRIVATE_KEY', // the application private key (RSA)
  vendorPublicKeyRef: 'ALIPAY_PUBLIC_KEY', // the Alipay public key responses are verified with
}

Both of an alipay-v3 instance's references are listed against it by the credential door, and setting or replacing either one re-materializes it. The keys are accepted as Alipay's console issues them (the bare base64 body) or as PEM.

What the platform does with it:

  • Every request is signed, each attempt fresh. A retry is signed again with a new nonce and date, so a scheme that refuses a replayed nonce or a stale timestamp accepts it.
  • The key never reaches the provider. The automation service binds the resolved key to the scheme's signer at materialization and hands the provider the signer only. A datasource cannot borrow a signed instance (external.connector is refused with 422): a driver cannot sign per request.
  • Schemes that sign their responses are verified before a result is returned; a response that does not verify fails the dispatch, and its body never reaches the flow.
  • aliyun-acs3-hmac-sha256 signs host, content-type and every x-acs-* header, and sets x-acs-date, x-acs-signature-nonce, x-acs-content-sha256 and Authorization. The API's own action and version are yours to send, as x-acs-action / x-acs-version in defaultHeaders (rest) or in each call's headers.
  • tencentcloud-tc3-hmac-sha256 signs content-type and host, and sets X-TC-Timestamp and Authorization. The service in the signature's scope is the first label of the endpoint host (cvm.tencentcloudapi.com, or a regional cvm.ap-guangzhou.tencentcloudapi.com, is cvm), so point baseUrl at the product's own endpoint. X-TC-Action, X-TC-Version and X-TC-Region are yours to send and are not signed. A request without a content type is sent with Content-Type: application/x-www-form-urlencoded, the type it is signed with.
  • alipay-v3 signs the method, the path and query as sent and the body, with a fresh nonce and millisecond timestamp, and sets Authorization: ALIPAY-SHA256withRSA app_id=…,nonce=…,timestamp=…,sign=…. Every response below status 400 must carry a valid alipay-signature (an empty body too), checked against the key vendorPublicKeyRef names; an error response is verified when it is signed, and an unsigned one fails as the error it is. Public-key mode only: Alipay's certificate mode is not supported.

What the publish door refuses:

  • An unknown scheme, at auth.scheme, naming the scheme it got and the ones this platform ships. A scheme joins the list only together with its signer and its test vectors, so a scheme the server cannot run is never accepted.
  • An inline key: secret, privateKey, secretKey or accessKeySecret is refused by name, pointing at credentialRef (on alipay-v3, appPrivateKey too, and alipayPublicKey points at vendorPublicKeyRef). The vendors' words for the key id (accessKeyId, secretId, appId) are answered with keyId. An authored signature is refused too: it is computed for every request.
  • provider: 'mcp', at auth.type: an MCP server is not signed per request. Declare provider: 'rest' or provider: 'openapi'.

signed and a static credential do not combine: a request is authenticated one way. An openapi instance's remote spec URL is fetched unsigned, as before; only the API calls are signed. A third-party provider factory serves a signed instance only when it says it applies the signer (requestSignerApplied on its materialization); one that does not is refused at boot rather than allowed to call the upstream unsigned.

The runtime shape: authentication

The authentication field is the runtime auth config, with four static variants (none, bearer, api-key, basic). It carries the resolved secret inline ({ type: 'bearer', token }), because it is supplied by host code (a plugin calling engine.registerConnector, or the executors' hand-wired instance options reading process.env). That is a different trust anchor than metadata: code review guards what enters it, and it is never serialized into a versioned artifact. On declarative entries, leave authentication alone — provider-bound instances must use auth, and catalog descriptors documenting a planned integration must still never carry a live secret value.

The runtime shape's oauth2 variant was removed in @objectstack/spec 18 (ADR-0143 D7): it held a client secret and a refresh token inline and nothing ran its lifecycle. authentication: { type: 'oauth2' } is refused with that prescription; declare the grant on an instance's auth instead, as above.

Dispatching from a flow

A materialized instance is dispatched exactly like any other connector — by name and action key:

{
  id: 'ping',
  type: 'connector_action',
  label: 'GET /api/v1/health',
  connectorConfig: {
    connectorId: 'billing_api',   // the connector's `name`
    actionId: 'request',          // rest: 'request' · openapi: operationId · mcp: tool name
    input: { method: 'GET', path: '/api/v1/health' },
  },
},

See Flows for the node reference and how outputs flow into downstream nodes.

Two packages, one connector name

Two packages that declare different namespaces may each declare a connector of the same name. Each is its own instance, held by its package and name: each is materialized, connected, credentialed and listed on its own (GET /api/v1/automation/connectors lists both, each descriptor carrying its packageId). Two packages of one namespace still may not, nor a package that declares no namespace beside another holder: the install is refused, naming both, as before. A deployment that already holds such a pair (code packages a boot only warns about) materializes each instance under its package, but no HTTP address tells them apart: the namespace door answers 409 for both. Give one of them its own namespace.

A bare name is resolved for whoever names it, and never picked between two holders:

Who names the connectorWhich instance it means
A flow's connector_action (connectorId)The flow's own package's instance, else the one holder in the package's declared dependencies; refused, naming every candidate, when its reach holds two or holds it only outside
A flow the environment authoredThe environment's own instance, else the one package holder; refused, naming both, when two packages hold it
A connector pull (mapping.connectorSource.connector)Resolved as a flow is, from the package that holds the mapping (an environment mapping: as the environment's flow). A refused name fails the pull 409 (connector_name_refused); a name that resolves to a package with no live instance is connector_not_registered, never another package's instance
The connection door, /api/v1/automation/connectors/NAME/connectionThe one holder of the name; 409 naming both when two packages hold it
The connection door at the namespace address, /api/v1/automation/connectors/NS/NAME/connectionThe instance of the package of namespace NS: connect, read and revoke each package's connection there
GET /api/v1/meta/connector/NAME409 naming both when two packages hold it; read each with ?package=ID or /meta/connector/NS/NAME

Each package's instance has its own connection per organization: connecting one leaves the other's untouched, and revoking one leaves the other serving.

A connector a plugin registers in code is no package's: it is dispatched by its name as before. A package may still declare a catalog descriptor of that name (an entry without a provider); the package's flows are then served the plugin's connector.

A disabled package holds no name for anyone else: its instance is not served to a caller outside the package, even before the next reconcile removes it. A flow of the disabled package itself still reads its own instance. An entry with no package of its own over a name only a disabled package holds is that package's instance, and is not dispatched until the package is enabled again.

Failure modes at a glance

Boot distinguishes configuration faults (your entry is wrong — fail loud, fix the metadata) from operational faults (the upstream is down — degrade, retry):

You wrote / it happenedWhat you get
provider names no installed factoryHard boot error naming the entry, the provider, and the plugin that supplies it — add the executor to plugins:
Invalid providerConfig (missing baseUrl / spec / transport, wrong shape)Hard boot error from the provider factory
auth is a grant-bearing kind (oauth2, app-credential) on a provider that does not ask the credential handle (a plugin's provider registered without { credentialHandle: true })Not fatal: the instance registers degraded, naming the kind, and the upstream is never called without its credential; a datasource borrowing it is refused with 422
An authorization_code instance nobody connected, or whose grant stopped working (the vendor refused it on refresh, no refresh token or client to renew an access token with, or the upstream refused its token at MCP tool discovery)Not fatal: the instance registers degraded, "not connected" or "reconnect required" — connect it (POST …/connectors/:name/connection), and it materializes without a restart
The token endpoint is unreachable or answers 5xx / 429Not fatal: the dispatch fails CONNECTOR_UPSTREAM_UNAVAILABLE and is retried on the existing backoff; the connection stays connected
auth is signed on a provider that does not say it applies the request signerHard boot error naming the instance, the scheme and the provider: its calls would go out unsigned — declare it through rest or openapi
credentialRef (or a signed instance's vendorPublicKeyRef) resolves to nothingNot fatal: the instance registers degraded, naming the reference — set it (PUT …/credential-refs/:ref), and it materializes without a restart
A signed reference resolves to something that is not a key of the scheme's kind (an alipay-v3 key that is not RSA)Hard boot error naming the instance and which reference cannot sign or verify, never the value
A response to an alipay-v3 call is unsigned (below status 400) or its signature does not verifyThe dispatch fails naming the instance and the status; the response's body is never returned
The upstream refuses the credential (401 / 403), or an mcp server sent a static credential does not list a tool the instance's include namesNot fatal: the instance registers degraded. A stored credential is marked rejected and waits until it is set again (or a restart); an environment or vault credential is retried on the backoff
Instance name collides with a plugin-registered connectorHard boot error — there is no silent precedence between the two worlds
Two entries of one package share a nameHard boot error naming the name and the package (a stored entry is logged and skipped): a name is unique within a package
An entry with no package of its own (one the environment stored, or an unstamped one) shares a name two packages holdNot materialized, refused naming both holders, since which package's instance it would be cannot be told: a host's own entry fails the boot, a stored or installed one is logged and skipped. Declare it in one of the packages, or under another name
stdio transport without host opt-inHard boot error with the declarativeStdio fix inline — a security rejection is never retried
An entry of an installed package (os package install, POST /api/v1/marketplace/install-local) names a package-relative file — an openapi spec path — or needs a location inside its package, as a stdio mcp transport's working directory doesConfiguration fault, never resolved against the host's directory: an installed package has no directory on the runtime it was installed into, and the host's is not its own. The instance is not materialized, and the reconcile's error names the entry, its package and the ref. Rebuild the package with a current os build, which carries an openapi spec file into the artifact, or inline the document; reach an MCP server from an installed package over http. Whether an entry is the host's is read from what the install recorded, never from the package's own words: an entry carrying a _packageId other than its own package's is refused at the install, every member of a packages[] bundle is recorded as installed whatever its source says, and an entry naming a package no registration records is refused its ref too. The host's own entries keep reading their files
A stored entry — one saved in this environment through the metadata door (PUT /api/v1/meta/connector/:name, Studio), environment-wide or in a package created here (POST /api/v1/packages) — names a package-relative file or needs a location inside a packageConfiguration fault, never resolved against the host's directory: a stored definition is no package's declaration and has no directory on disk. The instance is not materialized, and the reconcile's error names the entry, its package if it has one, and the ref. This one is never fatal, even at boot: a stored row at rest is logged and skipped, and the platform starts. Carry the document inline in the definition, or name it by an http(s) URL; reach an MCP server from a stored entry over http. Only what the host's own stack declares reads its files: a stored row is never read as the host's, whatever _packageId its body carries
MCP server unreachable / tools/list fails; remote spec URL unreachable or transiently failing (408/429/5xx)Not fatal: the instance registers degraded (visible on GET /api/v1/automation/connectors with the reason), dispatches fail with that reason, and the platform retries on a 5s→5min backoff — recovery is automatic
An mcp instance's toolsSnapshot does not match what the server serves (a pinned tool's description or inputSchema changed; or a pinned tool is no longer listed, on an instance whose credential did not reach the server)Not fatal: the instance registers degraded with no actions, its reason naming each tool and the digest it now serves, and the logs say "serves a tool definition that differs from its toolsSnapshot" (CONNECTOR_UPSTREAM_CHANGED); it is re-checked on the same backoff and recovers once the server serves the pinned definitions again — or set the pin to the reviewed digest. A pinned tool no longer listed on an instance whose credential did reach the server (its auth over http) takes the credential row above instead: a server may hide tools from a credential, so the reason names both causes (fix the credential and set it again, or update the pin), a stored credential is marked rejected, and no retry runs against the same value
A retry of a degraded instance reaches the upstream and meets a configuration fault (an include naming a tool or operation the upstream does not offer; on an mcp instance that sends a static credential, the credential row above applies instead)Not fatal: the instance stays degraded, now with the configuration reason, and is not retried — dispatches fail saying to edit its declaration; an edit of the entry (or a restart) re-attempts it
Wrong spec URL (other 4xx) or unparseable documentConfiguration fault — hard boot error
An openapi operation's parameter declares a style OpenAPI 3.x does not define for its location (deepObject on a path parameter, form on a header)Configuration fault — hard boot error naming the operation and the parameter; correct the document or leave the operation out of include
A connector_action input value whose shape the parameter's style has no encoding for (an array of objects for form, an object for a content-typed parameter)The step fails before dispatch naming the parameter, and nothing is sent
A connector_action input that, once evaluated, breaks the action's inputSchema (a missing required parameter, a wrong type)The step fails before dispatch with VALIDATION_ERROR, naming each parameter path, and nothing is sent; a fault edge or try_catch can route it. Supply the parameter or send the declared type: text is never converted, so cast it in a CEL envelope (int(), double(), bool()). GET /api/v1/automation/connectors lists the schema; os validate does not judge the input against the inputSchema yet
A bad entry arrives via runtime reload (a Studio publish, a direct active save through PUT /api/v1/meta/connector/:name, or a delete, made on any replica — peers reconcile on cluster lane 2; or a dev reload)Logged and skipped, never crashing the live server; a changed instance's old connector keeps serving until its replacement materializes
A bad entry belongs to a package installed into the runtime (POST /api/v1/marketplace/install-local), at the install or at a restart that registers the package againLogged and skipped, as on a runtime reload: the boot completes and the package's other instances materialize

Catalog descriptors: entries without a provider

An entry with no provider never reaches the registry — it is an inert descriptor for discovery, documentation, or marketplace listing. It may author actions (as documentation of a planned surface, including I/O JSON Schemas). Because a declared-with-actions connector that nothing registers is usually a mistake, boot warns about it — mark a deliberate descriptor with enabled: false to state the intent and silence the audit:

import { defineConnector } from '@objectstack/spec/integration';

export const ErpCatalogConnector = defineConnector({
  name: 'erp_catalog',
  label: 'ERP Integration (planned)',
  type: 'saas',
  description: 'Planned ERP integration — catalogued, not yet dispatchable.',
  actions: [
    { key: 'get_invoice', label: 'Get Invoice' },
  ],
  enabled: false, // deliberate catalog-only descriptor: suppresses the boot audit warning
});

A descriptor sharing a live connector's name stays legal — it is catalog metadata about that connector. (A provider-bound instance sharing one is the boot error from the table above.)

A complete, runnable example

The showcase app exercises every shape on a real boot — examples/app-showcase/src/system/connectors/index.ts declares a rest instance pointing at the server's own health endpoint, an openapi instance whose spec is a package-relative file, an mcp instance spawning the in-repo stdio fixture under a declarativeStdio allowlist, and a catalog descriptor — with flows dispatching the rest and mcp instances end-to-end. Start from it rather than assembling the shapes from scratch:

pnpm dev

Related pages: Flows · Webhook Delivery (the outbound-notification counterpart) · Connect an MCP Client (the opposite direction: exposing this platform to an external MCP client) · Connector schema reference (generated from the schema).

On this page