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).

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

Attachments

Scope	Grants
attachments:read	View attachments linked to transactions
attachments:write	Upload and delete attachments

Reports & Tax

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

Print

Scope	Grants
print-templates:read	View print template configuration
print-templates:write	Modify print templates (layout, colors, logo, columns)

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 consent includes it.