Sandbox, review, and production

What is available now#

Public operator registration and each integration's synthetic sandbox are available. Production data is intentionally disabled until BOT completes the mobile consent/upload rollout and every legal and operational release gate.

Sandbox access is real mTLS access to the real v1 contract, but every resource, history item, code, tombstone, and statistic is synthetic. Sandbox success never authorizes production data or commercial use. The current BOT Integration Terms apply throughout the lifecycle.

Synthetic corpus and provisioning#

Creating an integration queues its corpus; it does not generate hundreds of rows inside the browser request. The Sandbox page shows Queued, Preparing data, Ready, or a fail-closed attention state. Link-code generation remains disabled until the corpus is fully validated and atomically activated.

Corpus version sandbox-2026-09-v1 contains exactly 500 synthetic orders and 50 synthetic existing vehicles. Orders cover lifecycle and delivery-window changes, permitted shipping examples, resolved configuration, and reviewed option-code vocabulary. Vehicles contain plausible bounded telemetry and monotonic odometer history. Every resource is marked history_complete only after its complete generated history has committed.

The generator is deterministic for one secret/version/integration domain, but uses a distinct HMAC domain for every field and identifier. It composes new records from a reviewed static distribution model. It never selects, exports, shifts, hashes, or stores a mapping to a production order, account, VIN, vehicle, or history row. Changing dates alone is not anonymization and is not used by BOT's sandbox.

Every synthetic order's delivery_center ends with the exact suffix - SANDBOX. The same marked value appears in snapshots and any generated statistics, so screenshots, exports, and downstream test databases cannot be mistaken for production delivery-center data.

Integrations created before corpus version sandbox-2026-09-v1 are not reset silently. A BOT administrator runs the private, explicitly confirmed bin/sandbox-reset.php command for one reviewed integration ID. The command proves that every affected sandbox connection, grant, and alias belongs to a known synthetic identifier domain, preserves operator/profile/client/ certificate and all production rows, then queues the current corpus. Repeating the command is idempotent.

Environment separation#

Sandbox and production have separate clients, certificates, approved scopes, quotas, resource IDs, cursors, ETags, webhooks, and audit/usage streams. The base URL is the same; the verified client certificate selects the environment.

Never copy a sandbox cursor, fixture ID, certificate, or cached record into a production database. Use visibly separate secrets and storage namespaces.

Sandbox acceptance checklist#

• GET /capabilities identifies sandbox and the expected scopes.
• A leading-zero ten-digit code survives form transport and is redeemable once.
• The initial sync is applied transactionally before its cursor is committed.
• Delta sync and If-None-Match/304 behavior are covered.
• Every granted detail/history page is consumed and pagination is bounded.
• history_complete=false is represented as incomplete.
• A tombstone removes local individual and derived data.
• Deletion acknowledgement is idempotent and retry-safe.
• 429 honors Retry-After; 503 uses bounded backoff.
• Statistics are stored separately and contain no individual records.
• Logs and errors contain no certificate private key, link code, personal data, VIN, real order number, raw payload, or internal BOT identifier.

Review inputs#

Production review requires a complete integration profile, sanitized logo, public policies, public linking page, narrow scopes, accepted BOT credit/app link, polling/webhook concept, and a public review URL. The review URL should exercise the user-facing link flow with synthetic data and show the exact BOT attribution that will be used after launch. The credit and app link must be prominent and readable wherever BOT data is displayed.

The operator must explicitly accept the current version of the BOT Integration Terms before creating an integration and explicitly accept every later version. The standard licence is non-commercial only. Ads, Google AdSense, sponsorships, affiliate revenue, subscriptions, paid access, lead generation, data licensing/resale, and any other direct or indirect monetization are commercial use and require an individual written BOT agreement before that use begins.

For mixed-source output, every BOT-derived dataset, record, entry, chart series, or result must be identified directly where it is displayed. A footer or page-wide statement alone does not identify individual BOT-derived entries.

BOT reviews the current profile version. A material name, purpose, privacy URL, or scope change creates a new consent boundary and does not inherit approval or expand existing grants.

Status transitions#

sandbox → submitted → approved → active

BOT may transition a submission to rejected with notes. After approval, the integration owner explicitly uses Activate for production for the reviewed profile. BOT administrators may activate/reactivate operationally and may transition an active integration to suspended or retired when access must stop.

Approval accepts only the reviewed profile/scopes and permits production credential preparation. Owner activation is a separate explicit confirmation. Production API authentication requires active, and production data endpoints also require production_data_enabled=true.

Final activation gates#

BOT enables the separate production-data gate only after all of the following are satisfied:

• mobile app consent and upload behavior is released and verified;
• privacy/integration terms and retention periods have legal approval;
• production certificate issuance and real mTLS staging tests pass;
• operator deletion, revocation, rate limiting, and recovery behavior passes;
• the operator displays the mandatory BOT attribution and app link;
• the current Integration Terms version has been explicitly accepted;
• the intended use is non-commercial, or an individual written BOT agreement covers every commercial or monetized use;
• mixed-source output labels each BOT-derived record, entry, series, or result at its output point;
• rollback and operational monitoring are tested;
• BOT makes an explicit go-live decision.

Until then, keep production secrets unused and treat the sandbox as the only available data environment.

First production run#

1. Obtain a separate production certificate after approval.
2. Call GET /capabilities and verify environment, status, exact scopes, quotas, and production_data_enabled.
3. Stop if the integration is not active or the data gate is false.
4. Start GET /sync without a cursor and commit each page atomically.
5. Store only the final committed opaque cursor.
6. Begin the documented 15-minute poll cadence.
7. Monitor certificate expiry, last sync, rate headers, tombstones, deletion deadlines, and—if enabled—webhook dead letters.

No record appears merely because an integration is active. A signed-in BOT user must explicitly grant selected resources to the reviewed integration, and BOT must have received the allowed snapshot/history from the app.

Continue to monitor the terms version, attribution placement, data provenance, and business model after launch. A new terms version requires a new explicit acceptance. Adding ads, AdSense, paid access, sponsorships, affiliate revenue, resale, or any other monetization requires a written BOT agreement before the change goes live; neither production approval nor user consent grants that commercial permission.