Scopes

Scopes are the permissions a business grants your app on the consent screen. They are enforced per endpoint, deny-by-default: every API route declares the scopes it requires, and a token without them gets a 403. You cannot escalate a live token — to add scopes, send the user through authorization again with the wider scope value. Scopes bound what an app may request; some operations additionally require the consenting user’s business role — see Errors.

Tenant is implicit

There is no “which business” scope or parameter. The token itself is bound to the business that consented — never send business identifiers with API calls.

Request the minimum set your integration needs. The business sees every requested scope by name on the consent screen; over-asking costs you conversions and slows down review.

Scope catalog

:read grants view access, :write grants create/modify. This is the same registry the console’s scope picker uses (also served at GET https://api.getonebooks.com/developer/scopes).

Two scopes are reserved and not offered here

mcp:use and tally:sync are not partner scopes. Neither appears in the console’s scope picker, and an app registered in the developer console cannot request either one — which is why you won’t find them in the catalog below. Asking for one is rejected when you save the app.

Connecting Claude, ChatGPT, OpenClaw or a custom agent to a business over MCP is something the business does for itself, from inside the OneBooks app — see Connect AI agents (opens in a new tab). Those clients register themselves with the authorization server (RFC 7591 dynamic client registration, or a client ID metadata document), are clamped to a fixed AI-tool scope allowlist, and never pass through developer-console app registration or review.

tally:sync is first-party for a different reason: it gates the Tally migration pipeline, which stages and commits rows straight into a business’s ledger, and it belongs to the OneBooks Tally Client — a Windows connector that signs in with the device flow and is provisioned outside the console. Importing data as a partner goes through the documented import endpoints with ordinary scopes instead.

If your own integration has AI features, build them on the REST API with the ordinary scopes below. Everything the MCP tool surface can reach is a documented endpoint in the API reference — there is no partner path onto /mcp.

Identity

Scope	Grants
profile:read	View your profile information

Sales

Scope	Grants
invoices:read	View invoices
invoices:write	Create and modify invoices
customers:read	View customers
customers:write	Create and modify customers
quotes:read	View quotes
quotes:write	Create and modify quotes
sales-returns:read	View sales returns (credit notes)
sales-returns:write	Create and modify sales returns
payments:read	View customer payments
payments:write	Record customer payments

Purchases

Scope	Grants
suppliers:read	View suppliers
suppliers:write	Create and modify suppliers
purchases:read	View purchase orders / bills
purchases:write	Create and modify purchases
purchase-returns:read	View purchase returns (debit notes)
purchase-returns:write	Create and modify purchase returns
supplier-payments:read	View supplier payments
supplier-payments:write	Record supplier payments
expenses:read	View expenses
expenses:write	Record expenses

Accounting

Scope	Grants
journal:read	View journal entries
journal:write	Create journal entries
accounts:read	View chart of accounts
accounts:write	Create and modify accounts
contra:read	View contra vouchers (cash/bank transfers)
contra:write	Create contra vouchers
fiscal-year:read	View fiscal year and close status
fiscal-year:write	Lock or unlock fiscal years

Banking

Scope	Grants
bank-recon:read	View bank statements and reconciliations
bank-recon:write	Upload statements and match transactions

Catalog

Scope	Grants
items:read	View items catalog
items:write	Create and modify items

Reports & Tax

Scope	Grants
reports:read	View financial reports (P&L, Balance Sheet, etc.)
gstr:read	View and export GSTR-1 / GSTR-3B (India)

App platform

Scope	Grants
app-data:read	Read this app’s own data stored on your records
app-data:write	Store this app’s own data on your records
events:read	Read the event log (what changed, and when)

The Grants column is the registry’s own wording — it’s written to the merchant, which is why it says “your records”. app-data:* never exposes another app’s fields — your namespace is always derived from the token itself; see App data. events:read unlocks the Events API; each event in it is still filtered by that event’s own read scope (see the Event catalog).

Plans and the API

Every OneBooks plan — Free included — includes the OAuth API, webhooks and MCP. The merchant’s plan never decides whether your app can connect or call a route, so there is nothing to check during onboarding: scope and permission are the only two gates between a token and a 200. That holds for every app-platform capability too — embedded apps, app data, hosted functions and the marketplace are not gated by the merchant’s plan either.

What a plan does bound is volume, and only on invoice creation:

Plan	New invoices
Free	Up to a yearly invoice count and an annual turnover ceiling, both set per country
Standard	Up to a yearly invoice limit
Professional	Up to a higher yearly invoice limit
Premium	Unlimited

A POST /invoices past the ceiling returns 403 with a message naming the limit — whichever door the request came through, the app, your integration or an AI client. Nothing else changes: reads, payments against existing invoices and every other route keep working. Treat that 403 as “the merchant needs to pick a plan”, show them the message, and don’t retry.

Changing your app’s scopes

You can edit your app’s registered scope set in the console at any time, but:

• Widening the scopes of an approved app resets its review status to CHANGES_REQUESTED — it drops out of general availability until re-approved. Narrowing (or keeping the set identical) does not. See Go live.
• Existing consents are unchanged; each business’s grant stays at whatever it approved. To use a new scope with an existing business, re-run authorization with the wider scope request.

Scopes also gate webhooks: an event is only delivered if your app holds the event’s gating scope and the business’s installation of your app includes it — checked when the event is matched and again just before each delivery is sent.