Platform concepts
One set of concepts underlies everything in this section of the docs. Skim this page once before the others — the rest of the docs assume you know these terms.
The unit of registration in the developer console.
An app has a client_id, a secret (if CONFIDENTIAL), a set of registered
scopes, and optionally an appUrl (making it embeddable)
and a marketplace listing. One app can be installed into many businesses;
each installation is independent.
Installation
Section titled “Installation”The record of “this app is connected to this business” — one per app per
business. Created the first time a business connects your app — an
authorization-code or device-flow consent, a managed install from the
marketplace, or a sandbox install from the console — and holds the union of
scopes ever granted. An installation is ACTIVE or UNINSTALLED; see
Installation & lifecycle for the full state
machine, including the 48-hour data-redaction deadline after uninstall.
Scopes
Section titled “Scopes”The permissions a business grants your app, requested on the consent screen and enforced per endpoint, deny-by-default. Every token, session token and function run is capped by its installation’s scopes — see Scopes.
Session token
Section titled “Session token”A short-lived (60-second) signed JWT that OneBooks hands to your embedded app (running in the merchant’s browser), proving which user is looking at your iframe right now. It is not an API credential by itself — your backend verifies it on every request and, the first time it sees that business and user, exchanges it for a real access token it keeps. See Session tokens.
A record of something that happened in a business — invoice.paid,
customer.updated and 43 others, 45 in all. Events are kept for 30 days and
drive webhooks, the Events API
catch-up feed, and hosted functions. See the full
list on the Event catalog.
Extension
Section titled “Extension”A slot inside the OneBooks UI where your embedded app renders — an action
(opens your page in a dialog from a record’s Apps menu) or a block (an
inline card on a page, including the dashboard). Extensions point at a path
on your App URL’s origin. See UI extensions.
App data
Section titled “App data”Typed fields your app owns on a OneBooks record — a tracking number on an invoice, a loyalty tier on a customer. Visible to the merchant, optionally merchant-editable, and never part of the ledger, totals or tax. See App data.
Hosted function
Section titled “Hosted function”Your own JavaScript, uploaded to OneBooks and run automatically when an event you subscribed to fires — no server for you to operate. Runs in an isolated V8 sandbox with hard CPU, subrequest and egress limits. See Hosted functions.
Listing
Section titled “Listing”The marketplace-facing description of your app — name, tagline, description, screenshots, pricing, category — reviewed independently of the app itself. An app can be approved and used in production without ever being listed; a listing additionally makes it discoverable in the marketplace. See Publishing your app and Go live for how the two reviews relate.
Lifecycle at a glance
Section titled “Lifecycle at a glance”| Entity | States | Moves forward on |
|---|---|---|
| App review | DRAFT → SUBMITTED → IN_REVIEW → APPROVED (or CHANGES_REQUESTED / REJECTED, both resubmittable) | Submission in the console; see Go live |
| Installation | ACTIVE → UNINSTALLED | Consent creation (→ ACTIVE); merchant uninstall (→ UNINSTALLED); reinstall before redaction moves it back to ACTIVE with no data loss |
| Listing | UNLISTED → PUBLISHED ⇄ DELISTED | Approving a submitted revision (→ PUBLISHED); you unpublishing it, or OneBooks delisting it (→ DELISTED); republishing or a OneBooks relist (→ PUBLISHED) |
| Listing revision | DRAFT → SUBMITTED → IN_REVIEW → APPROVED (or CHANGES_REQUESTED / REJECTED); an approved revision replaces the previous live one, which becomes SUPERSEDED | Submitting edits; reviewer decision |
| Function version | created → activated (one activeVersionId at a time) | POST .../versions, then POST .../versions/:versionId/activate |
| Function run | QUEUED → RUNNING → SUCCEEDED / FAILED / SKIPPED | A matching event queues it; up to four attempts (immediate, then 30 s / 2 min / 10 min later) before FAILED — see Hosted functions |
Where next
Section titled “Where next”- New to the platform? Start with Getting started for the headless-API path, or the embedded app quickstart if you’re building something merchants open inside OneBooks.
- Building an embedded app? Installation & lifecycle and Embedded apps go deep on the two concepts above.