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
- You call the owner API over HTTP yourself: nothing breaks when the core moves to 1.11.0. Act
only if you want something a newer version added; pin the version and opt into detailed errors as described below.
- You use the TypeScript SDK 4.x or the Python SDK: the SDK asks the core for its version and
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.
- You operate the multi-tenant tier: each tenant has a default version. Tenants created now
get 1.11.0.
What each version added
| Version | Added |
|---|---|
| 1.1.0 | A forced checkpoint, /owner/v1/streams/{id}/checkpoint, so a client can settle and then revoke. |
| 1.2.0 | Reading a service node's protections, /owner/v1/nodes/{serviceNode}/protections. |
| 1.3.0 | Optional 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.0 | Mandates 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.0 | The 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.0 | Economic 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.0 | Own 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.0 | An 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.0 | Evidence 1.5.0, admin audit, terms-offer registration pin, and further additive surfaces (see the core CHANGELOG). |
| 1.10.0 | Additive close-shape fields for clients pinned at 1.10.0. |
| 1.11.0 | Card 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:
- Without the header, the tenant's default version applies. The default is set to the current
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.
- An answer to a request with a supported version (or none) carries a
Dynamo-Versionheader
naming the version served.
- An unknown version is refused with 400
version_unknown. - A route added after the version you pinned answers 404
version_unavailable, every route
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 at | What changes |
|---|---|
| 1.7.0 | The 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.0 | The 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_amended | revoked |
mandate_payee, mandate_window, mandate_limit, approval_required | cap |
mandate_assurance, mandate_verification, policy | cap |
| every other reason | unchanged |
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
- Read the core's version at
/owner/v1/version. - On the multi-tenant tier, send
Dynamo-Versionwith the version your code was written and
tested against. Raise it only after testing against the newer version.
- Send
Dynamo-Error-Detail: 1and branch onerrorDetail.code, not on the message text. - Ignore response keys you do not know. Do not send request fields your pinned version does not
list: the server refuses unknown fields.
- If you want behaviour that needs a pin (for example
minAgentVerificationor 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
- Each version's success and error bodies stay unchanged for a client that does not opt in.
- The wire compatibility suite replays recorded answers of 1.2.0, 1.3.0, 1.5.0, 1.6.0 and 1.7.0
against the current server:
cd "$DYNAMO_REPO"
pwd
make test-wire-compat
- The server refuses unknown request fields, so a mistyped field fails loudly and is never ignored.
- No owner-api version is deprecated in this release.