Core resource

Access tokens

An access token scopes a single participant to a single transaction. You hand the participant a URL; the token behind it validates on first use and is exchanged for a short-lived portal session JWT.

Mint a token

POST/api/v1/b2b/transactions/:id/access-tokens

Scope: transactions:write. The raw token is returned exactly once in the response body — store the full URL or the token itself before the request window closes.

Request bodyjson

{
  "role": "payer",
  "permissions": ["view_transaction", "fund_transaction"],
  "expires_in_seconds": 604800,
  "max_uses": null
}

Response 201json

{
  "id": "b2bat_…",
  "token": "htpk_live_…",           // shown ONCE — share with participant
  "url": "https://business.holdyn.io/portal/htpk_live_…",
  "role": "payer",
  "permissions": ["view_transaction", "fund_transaction"],
  "expires_at": "…"
}

The raw token is the credential. Anyone with the URL can open the portal and act with the granted permissions. Deliver it out-of-band (signed email, SMS) and treat it like a password.

Roles & default permissions

Role	Default permissions
`payer`	`view_transaction`, `fund_transaction`
`beneficiary`	`view_transaction`, `approve_milestone`
`viewer`	`view_transaction`

Revoke a token

DELETE/api/v1/b2b/access-tokens/:id

Idempotent. Emits access_token.revoked. Portal sessions minted from this token remain valid for their own 30-minute TTL — revocation is prospective, not retroactive.

Session exchange

Participant browsers call POST /api/v1/b2b/portal/session with the raw token in the X-Access-Token header. The response carries the portal session JWT — see Authentication.