Security

The platform’s security model

A few design decisions shape everything else on this site:

• Your code never runs inside OneBooks’ API process or database. Your app runs on your own servers, in the merchant’s browser inside a sandboxed cross-origin iframe, or in an isolated V8 sandbox for hosted functions. Every effect your app has on a business’s books goes through the same public API, permission checks and ledger invariants a human using the OneBooks UI would go through — there is no separate, less-checked path for integrations.
• Least privilege, bound to one business. Every credential — access token, session token, function run token — is bound to a single (user, business, app), and every API token is capped by that installation’s granted scopes and by the user’s role. A function run token is also short-lived — valid for at most five minutes, revoked when its run ends — and good only against the OneBooks API; treat it as a live credential all the same (see Run tokens). App data namespaces come from the token itself, never from anything in the request.
• Deny by default. Every partner-facing route declares the scopes it needs; a token without them gets 403, not partial access.
• Access ends immediately. An uninstall revokes your app’s tokens for that business on the spot and cancels any authorization still in flight — a code or approved device code you haven’t redeemed can’t mint new tokens afterwards. If OneBooks suspends an app, every token it holds is refused on the very next request, introspection reports them inactive and no grant issues new ones — no waiting for expiry.
• Limits apply before authorization. Partner API rate limits count every request a token sends, including ones then refused for a missing scope or permission, and repeated failed client authentications lock that client out of the token endpoints from that IP for a minute — see Rate limits.

Your checklist

Never ask for OneBooks credentials

Your app must never present a login form asking for a merchant’s OneBooks email or password. Session tokens exist specifically so an embedded app never needs one — a page that asks for OneBooks credentials is either broken or phishing, and it’s the fastest way to fail review.

• Store your client secret like a database password. Server-side only, in a secrets manager — never in a browser bundle, mobile app binary, or public repository. Token exchange specifically requires a confidential client for this reason.
• Verify every webhook signature, against the raw request body, with a constant-time comparison, accepting any v1= value during a secret rotation window. See Webhooks.
• Verify session tokens cryptographically on every request, against the published JWKS — never trust a base64-decoded payload without checking the ES256 signature, and never trust host, resourceId or other URL parameters as identity. See Session tokens.
• Request the minimum scopes your integration actually uses. Over-asking both slows down review and increases what a compromise of your app could reach.
• Set Content-Security-Policy: frame-ancestors https://app.getonebooks.com on every page you embed — without it, browsers won’t render it inside OneBooks at all. See Embedded apps.
• Use idempotency keys on every write you might retry — Idempotency-Key or a per-row idempotencyKey, so a network timeout or a queued retry can never double-post a document. See Integration patterns.
• Encrypt stored tokens at rest, both access and refresh tokens, the same way you’d treat any long-lived credential.
• Practice logging hygiene. Never log raw access tokens, refresh tokens, session tokens or webhook secrets — log a truncated suffix or a hash if you need correlation. Hosted function logs are redacted of the run token automatically; apply the same discipline to logs you control yourself.
• Declare hosted function egress explicitly — merchants see exactly which hosts your function talks to on your listing; keep that list accurate and minimal. Calls to those hosts go through the global fetch(), which never carries OneBooks credentials, and every redirect hop is checked against the same list — only ctx.api carries the run token, and only to OneBooks.

Reporting a vulnerability

Found a security issue in the platform itself — not your own integration? Email security@getonebooks.com. Don’t file it as a public issue or a support ticket.

Where next

Privacy & data handling covers the compliance side: data minimization, redaction deadlines, and the mandatory privacy webhooks.