Developer documentation
Your first exchange, with a real contract.
Use fictional data to exercise authorization, record ingestion, reviewed summaries, and revocation through the same scoped services.
The free local lab supports standards OAuth with PKCE and pushed authorization requests, plus signed durable webhooks. The original JSON preview remains compatible. Hosted sign-in and real vendor acceptance are still required.
Run the sandbox
From the Beans repository, use Node 24 and a local Docker engine. The sandbox creates and removes its own disposable database; it ignores production database credentials.
cd Services/LiveBroker npm ci --ignore-scripts docker pull postgres:17-alpine npm run connect:sandbox
- Open the local partner workspace.
Visit
http://127.0.0.1:18789/sandbox. Create an invitation and review it using the fictional Human reviewer or the configured native test build. - Approve only the test capabilities.
Partner tokens remain on the sandbox server. Use a fictional pet; the sandbox does not sign in to a real Beans account.
- Exchange and inspect.
Import a source record, request a summary, review the exact response, process delivery, and inspect the receipt and change feed.
- Test disconnect.
Revoke access and verify that subsequent partner reads are denied. Stop the command with Control-C to remove only its temporary database.
For an automated round trip, run npm run test:connect-roundtrip.
Exercise OAuth and signed webhooks
Open /oauth-lab on the running lab. Review directional permissions, connect through the independent OAuth client, verify a local TLS receiver, subscribe, and deliver a change event. Signing keys and tokens stay on the server; the lab uses clearly labeled fictional identity.
Manage a synthetic application
Open /workspace on the running local lab to register applications, inspect configuration revisions, manage verified staff roles, and request a local production review. The fictional staff session is separate from the synthetic Human reviewer. Read the administration and deployment guide.
Keep a local integration lab
Use npm run connect:lab -- --lab=partner-preview to retain the synthetic database and private test state across restarts. In a second terminal, run npm run connect:lab:worker -- --lab=partner-preview to process a bounded delivery batch independently of this browser. It stays on your computer and needs no additional hosted subscription.
Refresh the test session after access expiry. After revocation or the seven-day grant expiry, choose a new lab name for another exercise. Existing records and receipts stay in the original lab. This is local synthetic testing, not hosted production availability.
Build against a versioned contract.
const permissions = await client.capabilities(connectionID, accessToken); const records = await client.records(connectionID, accessToken); const requests = await client.requests(connectionID, accessToken); const changes = await client.events(connectionID, accessToken, savedCursor);
This client runs on your server. Never include invitations, verifier/state, bearer tokens, or callback queries in browser analytics or logs.
Follow changes without missing corrections.
The event feed reports record.changed, record.deleted, and summary.delivered. It contains resource references, not record bodies. Store the returned cursor only after applying the page.
Follow hasMore for additional pages. Cursors are authenticated and bound to the authorization and connection; they expire after 24 hours. A 410 means discard the expired cursor and establish a new checkpoint before scanning. resyncRequired means retained history is incomplete. Reconcile current records and replay changes from the new checkpoint; deduplicate by record ID and source revision.
For a lossless bootstrap, start the event feed first, retain its checkpoint, scan current records, then replay changes from that checkpoint. The full-record UUID pagination by itself is not an incremental feed.
Keep requests and responses connected.
Request a summary with a stable eventID. The Human can dismiss it or send an exact reviewed response. Requests distinguish awaiting review, response queued, completed, dismissed, expired, needs attention, and unknown delivery.
Only received summaries are readable through the partner delivery endpoint. A queued draft is never exposed. A resolved request no longer consumes the 100 pending-request allowance.
Security is part of the exchange.
| Boundary | Contract |
|---|---|
| Authority | Current app, environment, pet mapping, grant, owner authority, and token lifetime are rechecked. |
| Credentials | Short-lived access tokens; refresh rotation and replay invalidation; hashed server storage. |
| Retries | Stable event identity and reviewed content. Reconcile uncertain summary delivery instead of blindly resending. |
| Limits | Bounded payloads and response sizes, fixed pre-auth admission budgets, per-app limits, and Retry-After guidance. |
| Disconnect | New access stops; queued work is cancelled. Information already delivered cannot be recalled. |
Register verified HTTPS receivers in the organization workspace. Encrypted signing keys, signed endpoint verification, scoped subscriptions, bounded retries and explicit replay are implemented. The local lab proves the flow; hosted operation still requires deployment and identity acceptance.
Changelog
OAuth and webhook implementation · October 24, 2026
Standards OAuth/PAR, directional scopes, independent-client interoperability, Human consent, encrypted webhook registration and rotation, durable retries, signed local TLS delivery, and restart/restore evidence.
Hardening preview · October 24, 2026
Request completion and dismissal, scoped change events, admission controls, bounded worker and SDK calls, and refreshed developer documentation.
Foundation preview · October 23, 2026
Native Connections, invitation-based PKCE, source records, exact reviewed summaries, isolated synthetic adapters, and durable receipts.