Skip to main content
An Agent owner publishes a connection contract once so every publisher sees the same setup requirements. The contract is a non-secret definition: endpoint ownership, AdCP transport, typed publisher fields, supported authentication methods, production or sandbox posture, credential acquisition and rotation guidance, and documentation and support links.
Never put a credential value in a connection contract. API keys, passwords, tokens, private keys, and client secrets belong only in the connecting publisher’s secure credential form. They are not Agent metadata and are never sent through the model.If you paste a credential while drafting, remove it and rotate or revoke it immediately. If you suspect a credential was published despite validation, rotate or revoke it and contact Apostra support; do not try to repair an immutable version by publishing the same reference again.

​
Publish from the Agent Page

  1. Open Agents, then open an Agent your organization owns.
  2. Select Configure connection.
  3. Define the connection contract in the portable Task. The editor is always a new, unpublished draft; it never opens a published version for editing. To start from a published version, select Load vN as next draft beside that version. The Task reads that exact canonical id and version before loading it, then creates a draft at the next version after the highest published version for that contract id.
  4. Select Validate and preview to review the exact parsed contract a publisher setup will consume.
  5. Review the exact contract id and version, then publish.
Only a directly authenticated organization administrator can list, read, validate, or publish an owned Agent’s connection contracts. Service tokens, staff-assisted sessions, and impersonation cannot author them. Claim a Apostra-mapped Agent before publishing setup for it. An Agent can publish setup while it is registered or testing. Publishing setup does not activate any publisher connection. A connection still needs current Agent certification and every publisher-local authorization, credential, configuration, health, commercial, and readiness gate before it can become active.

​
What the contract defines

Authentication methods are selected from the platform’s closed union: no authentication, bearer token, API key, credential exchange, basic authentication, OAuth 2.0, or JWT. Platform service accounts are reserved for platform-owned built-in contracts. The owner defines the credential field schema and instructions. Each publisher supplies its own secret values in its own secure setup context.

​
Versions are immutable

Every published contract is identified by:
A publisher connection pins that exact reference. Do not edit or reinterpret a published version. To change fields or instructions, publish a higher version. Existing connections continue to resolve their pinned version; the platform never silently moves them to the latest definition. Loading a published version as a next-version draft is an explicit owner action. It does not change the published version or overwrite the current draft unless the exact canonical read succeeds. The Task waits up to 30 seconds for that read. If the read fails or times out, it keeps the current draft unchanged and offers a retry for that version. Contract ids have durable lineage. The first Agent capability to publish an id owns that id for every version; another Agent cannot reuse it. Ids used by platform built-in contracts are reserved across all versions. Choose a stable, Agent-specific id, then increment only its integer version when the definition changes. Each Agent capability can publish at most 25 contract ids and 250 total versions, with at most 50 versions for one id. A serialized definition cannot exceed 192 KiB. These limits include historical immutable versions. Credential guidance can explain how to request or rotate a credential, but it cannot include credential values or samples. A non-secret client field also cannot instruct a publisher to enter, paste, provide, supply, or upload a credential. Define credential collection under one of the supported authentication methods instead. Value-free statements such as where a token is available, how long it remains valid, or that no authorization is required are allowed; assignment-shaped headers and serialized examples are rejected. When an Agent has no owner-published contract, new publisher setup continues to use the generic external-sales-agent:v1 contract. The fallback does not copy or infer provider-specific behavior.

​
Task service boundary

The portable Task uses these organization-scoped service operations: These operations are dispatched inside the authenticated Agent Page through the Task service bridge. They are not part of the public Storefront REST API and are not a supported direct-client contract in the Storefront OpenAPI specification. Validation is stateless and does not reserve a version. Publication is the durable, immutable write. Both accept a contract object without provider identity; the API derives the provider organization and Agent capability from the authenticated owner boundary. The list operation is paginated with limit (default 50, maximum 100) and offset (default 0). Its result contains items with id, version, and displayName, plus nextOffset; request the next page while nextOffset is not null. Exact-version reads return the complete canonical contract and are not paginated.