Migrating owner-api 1.2.0 → 1.11.0

The owner API is the core's HTTP interface for budget owners. The current version is 1.11.0, and every version from 1.2.0 on is still served. Every minor version since 1.1.0 is additive and response-compatible: it adds routes and optional request fields, and a client that does not opt in gets the same answers it got before.

Back to Changelog, versioning, deprecation and migration.

Who has to act

only if you want something a newer version added; pin the version and opt into detailed errors as described below.

refuses a method the core is too old for before sending anything. Nothing to do here; see the SDK migration guide if you are on 2.x or 3.x.

get 1.11.0.

What each version added

VersionAdded
1.1.0A forced checkpoint, /owner/v1/streams/{id}/checkpoint, so a client can settle and then revoke.
1.2.0Reading a service node's protections, /owner/v1/nodes/{serviceNode}/protections.
1.3.0Optional mandate and category fields (a budget opened without a mandate gets the safe default), 409 mandate refusals, reservations (reserve, confirm, release), the signed authority chain and the budget tree.
1.4.0Mandates v2 (payee lists, time windows, per-transaction and per-period limits, approvals, depth 1 to 16), an optional anomaly envelope on stream open, confirming fewer units than reserved, and new routes: scheduler, reconciliation, freeze, thaw, stop, amend, approvals, the revenue switchboard, the request log, the budget list and network, alerts, and a webhook test.
1.5.0The checkpoint_pending refusal with a Retry-After header, late confirms after the reservation time-out (reservation_expired), the signed authority head, the full authority record set, and the evidence export.
1.6.0Economic accounts and identity links, the lowest payee identity level on mandates, signed webhook endpoints and the event catalogue, the main switch, top-ups, widgets, budget links and the end-user portal, the revenue summary, test fixtures, opt-in pagination and Dynamo-Version pinning on the multi-tenant tier, and payment authorizations, receipts and records.
1.7.0Own hops on stream opens (a delegation signed by the delegator, a payeeOffer signed by the payee), requestRef on opens, credit card payee admission, the stream's payment authority and consume rows, the payee surface under /payee/v1/, scoped credentials, SD-JWT key binding, the terms catalogue and breach reports, and adopting a user-owned contract v2 budget.
1.8.0An optional mandateHash on a delegation (see hop intent v2), the Task Allowance, the fee read, adopting a child stream on contract v2, the oracle's breach attestation route (Preview, behind CORE_ORACLE_ATTEST), and route groups for ramps (Preview), agent verification (Preview), card agent programs (Preview), human payments, policies, recourse, organisations and cost reports.
1.9.0Evidence 1.5.0, admin audit, terms-offer registration pin, and further additive surfaces (see the core CHANGELOG).
1.10.0Additive close-shape fields for clients pinned at 1.10.0.
1.11.0Card hold states on the budget read, card payee-held alerts, and additive reservation fields for clients pinned at 1.11.0. Human funding-options may carry chainId at this pin.

For each route's exact version, read the core's OpenAPI document at /owner/v1/openapi.json.

Pin a version with Dynamo-Version (Live)

A request may name the owner-api version it was written for in the Dynamo-Version header.

On the multi-tenant tier:

version when the tenant signs up. /tenant/v1/settings shows it and the list of supported versions, and a PUT to the same route with {defaultVersion} changes it.

naming the version served.

included (portal tokens, end-user budgets, revoking a developer token and the test fixtures at 1.6.0, and the payee's payout destinations at 1.7.0 joined the gate in the V2 fix pass).

On a single-tenant instance no route is hidden by version. The header only turns on the answers listed in the next section.

Answers that depend on the pin

A few answers differ by pin. A client pinned below the version in the first column, or sending no version, keeps the earlier answer byte for byte.

Pinned atWhat changes
1.7.0The event catalogue at /owner/v1/events/catalogue is the 1.5.0 edition (below 1.7.0: the 1.4.0 edition). Re-linking an identity proof that is already linked answers 409 conflict.
1.8.0The event catalogue is the 1.6.0 edition. A mandate may carry minAgentVerification; without the pin that field is unknown and refused. Evidence can be exported as ?schema=1.4.0. A policy refusal names policy as the halt reason (earlier pins see cap). Approvals carry clientKeyed. The budget network carries the cap refusals. Account errors use the corrected doc_url path. Re-presenting a linked SD-JWT credential counts as the same link. A stream's terms read carries breachSigner. Adopt-prepare also answers the ids and the root hop intent, and a failed adopt answers 409 adopt_refused (see contract v2). An adopted budget without its owner's signed root hop is refused evidence 1.3.1 and 1.4.0 under required own hops (409 hop_unsigned).

Ask for detailed errors with Dynamo-Error-Detail: 1 (Live)

Routes that existed in 1.3.0 answer their 1.3.0 error body unless the request sends Dynamo-Error-Detail: 1. Routes added from 1.4.0 on always answer the detailed form.

The detailed form is the earlier body with the precise reason, plus an errorDetail object: type, code, message, param and doc_url, and, where they apply, headroom and fix. The SDK 3.x sends Dynamo-Error-Detail: 1 on every request.

Halt reasons for clients written before 1.4.0

Owner-api 1.4.0 added halt reasons that a 1.3.0 client does not know. A client that does not send Dynamo-Error-Detail: 1 receives the older reason it knows instead:

Precise reason (detailed form)Reason a pre-1.4.0 client receives
frozen, stopped, mandate_amendedrevoked
mandate_payee, mandate_window, mandate_limit, approval_requiredcap
mandate_assurance, mandate_verification, policycap
every other reasonunchanged

The one exception: a client pinned at 1.8.0 receives policy itself in the older body. Opt into detailed errors to see the precise reason on every route.

Steps

  1. Read the core's version at /owner/v1/version.
  2. On the multi-tenant tier, send Dynamo-Version with the version your code was written and

tested against. Raise it only after testing against the newer version.

  1. Send Dynamo-Error-Detail: 1 and branch on errorDetail.code, not on the message text.
  2. Ignore response keys you do not know. Do not send request fields your pinned version does not

list: the server refuses unknown fields.

  1. If you want behaviour that needs a pin (for example minAgentVerification or evidence 1.4.0

at 1.8.0, or 1.11.0 card hold fields), pin that Dynamo-Version. This applies on a single-tenant instance too. New work should pin 1.11.0.

Compatibility guarantees

against the current server:

cd "$DYNAMO_REPO"
pwd
make test-wire-compat