1. Create an isolated workspace
For the quickest setup, connect an agent. One form creates its identity, merchant permission and scoped key. Download the Node.js and Python kit, extract it on your agent server, then run node --env-file=.env check.mjs or python3 check.py. No package installation is required. The test records a permission decision without making a payment. Use the merchant execution integration below before running real actions.
Create a BoundProof account, register an agent and grant a permission in the workspace. Copy the agent ID and permission ID. Create a merchant workspace key under API keys.
Existing Hub accounts, aio_ keys, plans and proof balances are not imported. No paid subscription is created in this pilot. The new backend reuses permission evaluation logic from the Apache-2.0 AffixIO SDK 1.4.1, with its own database and signing key.
Download merchant.mjs AffixIO SDK on npm
export BOUNDPROOF_API_KEY='your-server-side-bp_live_key' node your-merchant-server.mjs
The connector uses Node.js 20+ built-in fetch and has no extra dependencies. Keep the API key in server-side configuration. Do not load this module in a browser.
2. Submit a server-validated action
Build this object from your own trusted order records. Do not accept the amount, merchant, currency, agent ownership or permission ID directly from an unauthenticated browser request. Authenticate the caller and confirm its ownership of the order first.
const action = {
agent_id: 'your-registered-agent-uuid',
merchant: 'example-store',
action: 'purchase',
currency: 'GBP',
amount_minor: 3500,
order_ref: 'order-1042'
};Amounts use integer minor units: 3500 means £35.00 for GBP. Supported currencies are GBP, USD and EUR. Match the merchant identifier exactly. Include a unique order reference and reuse the same request UUID when retrying the same evaluation.
import { BoundProofMerchant } from './merchant.mjs';
import { randomUUID } from 'node:crypto';
const bp = new BoundProofMerchant({
apiKey: process.env.BOUNDPROOF_API_KEY
});
const receipt = await bp.evaluate({
requestId: randomUUID(),
mandateId: permissionId,
action
});The result is { payload, attestation }. Inspect payload.decision: allow, deny or review. A repeated request ID with changed content returns 409.
3. Consume before your payment call
if (receipt.payload.decision === 'allow') {
const result = await bp.execute({
decisionId: receipt.payload.decision_id,
action,
perform: async ({ action, idempotencyKey }) => {
return yourPaymentService.create(action, { idempotencyKey });
}
});
}yourPaymentService is your own payment adapter, not a function supplied by BoundProof. It must enforce your provider's idempotency contract and existing authentication and fraud controls.
The server rechecks the active agent, permission, expiry, exact action and remaining budget. It atomically consumes the decision and deducts the permission budget. The callback is not called when consumption fails.
4. Bring a person in when needed
A review result waits in the workspace's Approvals tab. The workspace owner sees the exact merchant, agent, order, amount and expiry. Approval cannot turn a hard policy denial into permission.
After approval, fetch the updated decision with bp.getDecision(decisionId). Only consume it when its state is allow. All decisions expire after ten minutes, including pending approvals.
Creating a permission or approving a request requires an authenticated owner session and CSRF protection. Agent API keys cannot create permissions, approve actions or consume execution authority.
API reference
Base URL: https://boundproof.affix-io.com. Use Authorization: Bearer bp_live_... for authenticated integration routes.
| Method and path | Purpose | Access |
|---|---|---|
| GET /api/v1/me | Current workspace and agent scope | Merchant or agent key |
| POST /api/v1/decisions | Evaluate request_id, mandate_id and action | Merchant or scoped agent key |
| GET /api/v1/decisions/:id | Read current state and signed receipt | Same workspace and agent scope |
| POST /api/v1/decisions/:id/consume | Reserve exact action once; body is { action } | Merchant key only |
| GET /api/public-key | Service ML-DSA-65 public key | Public |
| POST /api/verify | Verify { payload, attestation } | Public, rate-limited |
401 means missing or invalid credentials; 403 means forbidden scope; 404 does not expose records from other workspaces; 409 means changed, expired or already-consumed state; 429 means a rate or pilot limit. Any failure must stop execution.
Limits: 50 agents and 30 active keys per workspace, 150 new evaluations per rolling 24 hours. Public sandbox requests have a separate limit. These limits are not a paid AffixIO SDK proof allocation.
Check receipt integrity
Use the receipt verifier or POST the receipt to /api/verify. The verifier checks against the service's configured key, never a key supplied by the receipt.
Offline verification must pin the trusted service public key from /api/public-key, recursively sort object keys, preserve array order, encode the resulting JSON as UTF-8, hash it with SHA-256 and verify the ML-DSA-65 signature over the digest bytes. This is an independent BoundProof signing identity, not the key at api.affix-io.com.
Receipt integrity is separate from current authority. Even a correctly signed allow receipt must go through the online consume check. The pilot issues signed attestations, not zero-knowledge proofs.
Relay: requests between agents
Relay is optional and free during the beta. Turn it on for an agent in the workspace Relay tab and it gets a signing key and a public agent-relay/1 inbox. It can then send signed, proof-backed requests to other agents with its normal agent key, and you approve what arrives. Held requests can be approved for 60 minutes after they arrive. It does not use your evaluations or any AffixIO proof allowance.
curl -s https://boundproof.affix-io.com/api/v1/relay/send \
-H "Authorization: Bearer $BOUNDPROOF_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{"to_url":"https://boundproof.affix-io.com/api/relay/<id>","action":"quote.request","params":{"sku":"W-9","qty":12}}'Read how Relay works or see the open-source AffixIO Agent Relay.
Before production use
- Connect permissions to your authenticated customer or employee authority. The pilot only records workspace-owner grants.
- Require the gate on every covered backend execution path.
- Keep payment credentials and card data outside BoundProof.
- Implement payment-provider idempotency and reconciliation.
- Arrange independent security testing, operational monitoring, backup recovery and key-rotation procedures.
- Agree data retention, support and commercial terms before handling production customer workflows.
Company invitations, enterprise SSO, verified consumer mandates, shared Hub billing, automatic refunds and payment-webhook reconciliation are not included in this pilot. The service does not establish KYC, cardholder authentication or legal compliance.