Get or renew scoped access#
GET /v1/routing/access discovers programs owned by the verified account without issuing credentials. The browser checks this before asking for a reviewer. Explicit renewal preserves the selected program’s reviewer and profile, issues seven-day access and revokes only that program’s older credentials. Losing a reviewer private key cannot be repaired by renewing API access. Use the account session and exact sandbox Origin for browser writes; scoped provider credentials cannot manage account setup.
Check successor_enabled in account discovery before explicit successor setup. When enabled, POST access requires action (create, renew or successor), a stable request_id UUID, deployment_id, profile and reviewer_public_key; renewal or successor also names the owned program_id. A successor must name the latest predecessor. Up to three lifetime programs share 20 purchases and two merchant registrations per account/deployment; all deployments share three credential issues per account/day, with 20 new programs globally per UTC day. Historical agreements, debt, authorizations and reviewer bindings stay unchanged. A wallet already registered on the deployment cannot move to a successor.
Keep the same public request and UUID across an uncertain retry. ACCESS_ALREADY_ISSUED means it committed; the server never replays its credential. Discover the program, use your saved access file, or explicitly renew if the response was lost. A new successor request cannot bypass an existing successor. The client routingAccountAccess helper uses a verified account token, separate from the program credential; omit body for discovery.
Service scopes#
| Scope | Authority |
|---|---|
| merchants:write | Create merchant terms; confirm wallet enrollment. |
| purchases:write | Create, register and reconcile purchases; dispatch signed notifications. |
| claims:write | Submit exact buyer-signed claims and matching chain receipts. |
| decisions:write | Submit designated-reviewer signatures. Does not confer review authority. |
| refunds:execute | Execute already approved purchase-bound refunds. |
| records:read | Read scoped records, transaction hashes and signed notification receipts. |
Send Authorization: Bearer <credential>. Credentials last seven days. Renew through the original verified account using the same reviewer; renewal revokes the prior credential. Provider routes reject browser cookies. Keep the access file private.
Existing-wallet permissions#
Merchant links expire after seven days. Buyer links last through the purchase’s immutable collection deadline, at most 150 days. A link grants access only to its record and permitted wallet-proof actions; it cannot approve or execute refunds. Cleard-Wallet-Access carries the link capability. URL fragments are removed after the page loads.
V4 supports policy-selected reserve or direct-wallet funding. Direct mode requires a signed mandate plus separate allowance and is available only when the program advertises direct_wallet. See Direct merchant-wallet mode. The merchant signs exact funding authorization and an onchain enrollment. The buyer authorizes the exact payment and files its claim. Neither a provider credential nor a wallet link replaces these wallet signatures. No arbitrary external wallet can be debited.
Designated reviewer#
Reviewer Ed25519 keys and EVM wallet keys are separate. The reviewer signs the exact purchase, terms hash, evidence hash, amount, beneficiary and expiry. Provider administration cannot substitute another reviewer. In the browser, the private key file remains local and only the signature is sent.
Routing OpenAPIAccount, scoped service and wallet-link security definitions.