Sandbox

A sandbox is a real OneBooks business owned by your organization — provisioned through the same tenant-creation path as a production signup, with a real chart of accounts and a real ledger. Nothing about it is mocked: an invoice you push into a sandbox posts genuine journal entries you can inspect in reports.

Create sandboxes on the Sandbox page of the developer console (org admins only). Each org can have up to 3 sandbox businesses at a time.

One-time credentials

Creating a sandbox returns an owner login:

{
  "businessId": "…",
  "businessName": "…",
  "ownerEmail": "sandbox-ab12cd34@sandbox.getonebooks.com",
  "ownerPassword": "…"
}

Use these credentials to:

Sign in to the OneBooks app at app.getonebooks.com (opens in a new tab) — set up test customers, items and settings the way a real merchant would.
Complete the OAuth consent flow — when your app redirects to the authorization page, log in as the sandbox owner and approve. The resulting tokens are scoped to the sandbox business.

Install your app into a sandbox

Building an embedded app? You don’t need to walk through a full browser OAuth redirect every time you want to test it. Open your app in the console, go to its Embedding tab, and use the Install in a sandbox panel: pick one of your org’s sandbox businesses and select Install (org admins only; there’s no CLI command for this today). That creates an ACTIVE installation directly, for the sandbox’s owner, with your app’s full registered scope set and no consent screen in the way — and sends your app app.installed with source: "SANDBOX", just as a real install would.

This is the fastest inner loop for testing UI extensions and hosted functions end to end: sign in to app.getonebooks.com (opens in a new tab) with the sandbox owner credentials, open a record, and your extension is already there. It works whether or not your app has completed review or has a marketplace listing — both of those gate connecting to other businesses, never your own sandboxes.

Changed your app’s scopes since? Install again from the same panel — the installation’s scopes grow to your app’s current set (they’re a union; see Installation & lifecycle).

The review gate

Sandboxes are how you develop before your app is approved:

An app that hasn’t passed review can only complete authorization against its own org’s sandbox businesses. Attempting to connect any other business fails with 400 — enforced server-side at both the consent step and the authorization-code exchange.
Once approved, the app can connect to any OneBooks business. Sandboxes keep working exactly as before — keep one around for regression-testing releases.

The review submission also asks you to confirm you’ve tested the integration end-to-end against a sandbox, so build that habit early.

Removing a sandbox

Deleting a sandbox from the console immediately revokes its OAuth consents/tokens and owner sessions. Removal frees a slot toward the cap of 3.

What sandboxes are not

Not anonymized production data. They start empty; you create the test data.
Not rate-limit exempt. The same limits apply.
Not a separate API. Same hosts, same endpoints, same webhooks — only the consenting business differs, which is exactly what makes sandbox testing representative.

Privacy Cookies