Widgets, budget links and the portal
Three ways to show an end user what their money funds. Each uses a short-lived, single-purpose browser token minted by your server; an API key or owner token is never accepted on these surfaces (the owner token gets owner_token_refused, an API key token_malformed), and a token of one kind never opens another surface (token_wrong_kind on a single-tenant core; the multi-tenant (hosted) front door answers token_malformed).
Widgets
One static script, no framework:
<script src="https://dynamo.example.com/widgets/v1/dynamo-widgets.js" defer></script>
<dynamo-balance base="https://dynamo.example.com" token="dx1.wgt.…" refresh="10"></dynamo-balance>
<dynamo-receipts base="https://dynamo.example.com" token="dx1.wgt.…" limit="20"></dynamo-receipts>
<dynamo-tree base="https://dynamo.example.com" token="dx1.wgt.…"></dynamo-tree>
<dynamo-approvals base="https://dynamo.example.com" token="dx1.wgt.…"></dynamo-approvals>
Mint the token per page view:
cd ~
pwd
curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/widget-tokens" \
-H "Authorization: Bearer $DYNAMO_API_KEY" -H 'content-type: application/json' \
-d '{"budgetId":"bud_…","scope":"read","ttlSeconds":300}'
A widget token is bound to one budget, is read or approve scoped, and lives ttlSeconds (default 300, at most 900). <dynamo-approvals> needs an approve token to approve or reject (scope_insufficient otherwise).
A held stablecoin open on contract v2 that your client keyed completes only with the session key of the client that opened it, and the core never holds that key. <dynamo-approvals> and the console show such a hold as "approve from the client that opened it" and offer Reject only; approving it here answers client_keyed_hold and the hold stays pending. If that client lost its key (for example a restart), reject the hold and open the stream again.
Origins: the widget data routes answer the deployment's own origin and the exact origins listed in CORE_WIDGET_ORIGINS; any other Origin is refused with widget_origin_refused.
Budget links
A read-only page for one budget, safe to send by email:
cd ~
pwd
curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/budget-links" \
-H "Authorization: Bearer $DYNAMO_API_KEY" -H 'content-type: application/json' \
-d '{"budgetId":"bud_…","ttlSeconds":604800}'
The answer's url is /b/<token>. ttlSeconds is 60 to 2592000 (default seven days). Add ?format=json for the same view as JSON.
The end-user portal
The portal shows every budget linked to one end user, what each funds, the latest receipts and the spend, and lets the user freeze or revoke a stream. Revoke settles the payee's signed work first; if a settlement fails, the revoke still goes ahead and the unsettled streams are named in the revoke's signed authority record. A revoke on a stream bound to a task whose claim window is open is held: the page says it is held for a task claim (the JSON answer adds held: true), nothing more is spent from the stream, and it stops once the window closes. Each action writes a signed authority record. On a multi-tenant (hosted) deployment the front door serves the portal page but not its freeze and revoke actions in this release; those actions work on a single-tenant core.
cd ~
pwd
curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/end-users/user-42/budgets" \
-H "Authorization: Bearer $DYNAMO_API_KEY" -H 'content-type: application/json' \
-d '{"budgetId":"bud_…"}'
curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/portal-tokens" \
-H "Authorization: Bearer $DYNAMO_API_KEY" -H 'content-type: application/json' \
-d '{"endUserRef":"user-42","ttlSeconds":3600}'
Budgets funded through the top-up page are linked to their end user automatically. The portal answer's url is /portal/<token>; the portal token's ttlSeconds is 60 to 86400 (default 3600).
Revoking a browser token
POST /owner/v1/devx-tokens/:id/revoke revokes any widget token, budget link or portal token by its id (tokenId, linkId or portalId).
Error codes
widget_origin_refused
The page's origin may not call the widget routes. Serve the page from the deployment's origin, or ask the operator to add the exact origin to CORE_WIDGET_ORIGINS.
owner_token_refused
Browser surfaces never accept the owner token (this code) or an API key (an API key answers token_malformed). Mint a scoped token server-side.
scope_insufficient
Approving or rejecting needs an approve-scoped widget token.
client_keyed_hold
The held open completes only with the session key of the client that opened it. Approve it from that client, or reject it here. Nothing was opened and the hold stays pending.
end_user_budget_conflict
The budget is already linked to another end user.
csrf_invalid
A portal action was not submitted from the page that rendered it.
Token codes
token_missing
No token was sent. The app's server mints one and passes it to the page.
token_malformed
The token is not in the minted form. Use it exactly as minted.
token_wrong_kind
Each surface takes its own token kind (widget, budget link, portal, top-up). Mint the right one.
token_signature_invalid
The token was altered. Mint a new one.
token_expired
The token has expired. The app mints a new one.
token_revoked
The token was revoked or is unknown on this deployment. The app mints a new one.