Api Trigger Secret Ref — Automation Protocol

An inbound api hook's secret, by reference.

An api flow's start node arms an inbound hook that verifies every post against a per-flow HMAC secret (ADR-0041). Until this key the only way to declare that secret in a definition was the literal config.secret, so an app package could not ship an api flow without publishing its credential: a packaged flow cannot be overlaid, so the write-only flow credential store the metadata save door fills is out of a package's reach.

config.secretRef names the secret instead of carrying it. The deployment supplies the value under that name, and the automation engine reads it at every inbound post through the same credential resolver a declarative connector's auth.credentialRef goes through (ADR-0097 §3): an environment variable of that name in the open tier, a secrets service where the host wires one. A post that arrives while the name resolves to no value is refused as unavailable, never verified against nothing.

The reference is NOT a credential: it is served with the definition like any other key, and only the literal config.secret is withheld on read.

Three refusals, each anchored on the start node's config:

• a reference that is not a name — ApiTriggerSecretRefSchema;
• a start node that declares both secret and secretRef — two sources for one credential, and no reader could say which one an author meant;
• a reference on a flow that binds no inbound api trigger — nothing would ever read it, so a deployment would fill a name for nothing.

TypeScript Usage

import { ApiTriggerSecretRefSchema } from '@objectstack/spec/automation';
import type { ApiTriggerSecretRef } from '@objectstack/spec/automation';

// Validate data
const result = ApiTriggerSecretRefSchema.parse(data);

ApiTriggerSecretRef

The name of the inbound hook's HMAC secret, filled by the deployment and read at every post through the automation credential resolver (an environment variable of that name in the open tier). In place of a literal secret, never beside it; not in the OS_ namespace.