Installation & lifecycle

An installation is the record of “this app is connected to this business” — one per app per business. It’s created the first time a business connects your app, and it’s what caps every token, session token and function run to that business’s granted scopes. Webhooks, hosted functions, app data and UI extensions all key off an ACTIVE installation.

Ways to install

	Managed install	Redirect install
Requires	An App URL (your app is embeddable) and a published listing	Nothing extra — works for any app; set an installUrl on your listing for the marketplace’s Install button
Merchant flow	Selects Install, confirms the permissions dialog; no browser redirect	Selects Install; sent to your installUrl, where you run standard OAuth authorization code + PKCE, and they approve the consent screen
Scopes granted	Every scope your app requests	The scopes in your authorization request
Where your first token comes from	Token exchange, the moment your app’s page first loads	The authorization-code exchange, as Authentication describes
app.installed source	MARKETPLACE	OAUTH

Two more paths create installations too: the device flow (Authentication, source: "DEVICE") and a console sandbox install into one of your own sandbox businesses (source: "SANDBOX"; see Sandbox). All of them converge on the same result: an ACTIVE installation holding the scopes that were granted, and normal access/refresh tokens for whichever user completed the flow. What merchants see shows both install flows from the merchant’s side.

Note

Each of those consents upserts the installation. Scopes accumulate as a union: if a business re-authorizes with a wider scope set later, the installation’s scopes grow to match; they never shrink except on uninstall. Token exchange is different: it never creates an installation — it requires an ACTIVE one — and only records a consent for the user who has your app open.

Lifecycle events

Three events go only to your app (audience app, matched by clientId, ignoring installation state — an uninstall notice is sent precisely when there is no active installation left):

Event	Fires when
app.installed	An installation moves from nothing/UNINSTALLED to ACTIVE
app.uninstalled	A business uninstalls your app
app.scopes_updated	The scopes on an existing installation change

Each is sent once the change has been committed. Two more app-targeted events follow from an installation’s life: business.redact (below) and app_data.updated, when a merchant edits one of your app data fields.

Uninstall

DELETE /apps/installed/:clientId (merchant-initiated, integrations.manage) does all of this in one transaction:

1. Marks the installation UNINSTALLED.
2. Revokes every consent, access token and refresh token your app holds for that business.
3. Cancels every authorization still in flight for that business: codes you received but haven’t redeemed yet, device codes a user approved that you haven’t polled for, and consent screens still open.

Once that commits, OneBooks emits app.uninstalled.

From that moment your app stops receiving that business’s business and privacy events (app-targeted notices such as business.redact still arrive), queued or retrying deliveries of those events are dropped, and your UI extensions and home page disappear from that business.

Tokens die immediately, not at their natural expiry

Your next API call with a token from this business returns 401 right away — there’s no grace period. Treat 401 (after a failed refresh) as “this business uninstalled you” and stop retrying.

Nothing can bring those tokens back. Every grant checks, at the moment it issues tokens, that the installation is still ACTIVE — and code, device-code and refresh grants also that the user’s consent stands — so a code, device code, refresh token or token exchange that reaches /oauth/token after the uninstall gets invalid_grant. A grant that was already being issued when the uninstall landed has its tokens revoked with the rest.

The per-user disconnect on a business’s Integrations page (for a single user’s connection) revokes that user’s consent and tokens. When it removes the last active consent for your app, the installation becomes UNINSTALLED too and you get app.uninstalled, with the same consequences as above — every later grant for that business gets invalid_grant. While other users of the business still have your app connected, the installation stays ACTIVE — and if the user who disconnected is the one it acts for (the installer, whose permissions hosted functions run with), it passes to the remaining connected user who connected first.

Redaction — 48 hours later

If the installation is still UNINSTALLED 48 hours after app.uninstalled, OneBooks:

• deletes every app data value your app stored in that business,
• stamps the installation redactedAt, and
• sends business.redact to your app.

OneBooks checks for due installations hourly, so business.redact can arrive up to an hour after the 48-hour mark. If the notice can’t be recorded on one check, the next hourly check sends it again; and it’s never sent to an app the business reinstalled in the meantime. Your app must delete whatever it independently stored for that business on receiving it — this is the same “mandatory compliance webhook” pattern used industry-wide, and both app.uninstalled and business.redact are required subscriptions for a marketplace-listed app; see Privacy & data handling and Publishing your app.

Reinstall

If the business installs your app again before the 48-hour window closes, the installation simply moves back to ACTIVE — no redaction happens, and nothing was deleted on the OneBooks side. Your own systems should handle this gracefully too: an app.uninstalled followed by a fresh app.installed for the same business is a normal “changed their mind” sequence, not an error. A reinstall after redaction starts over: the installation becomes ACTIVE again, but the app data deleted at redaction is gone.

Where next

Embedded apps for what happens once your app is installed and a merchant actually opens it.