Scopes

The canonical scope model — 50 scopes across every public resource, enforced identically for API keys and OAuth tokens.

Every public-API-accessible route declares the scope(s) it needs. Whichever credential you use — API key or OAuth token — VUZ checks for an exact string match against the scopes granted to that credential. No wildcard expansion, no implied hierarchy (documents:write does not imply documents:read).

Scopes follow a resource:action pattern. Most resources have a :read and a :write scope; a few high-stakes actions get their own dedicated scope (finalizing, cancelling, charging, sharing, and requesting a Tax Authority allocation for a document are each separate grants — a key that can create drafts cannot silently issue or charge them).

The 50 canonical scopes

Each endpoint page in the API Reference shows the exact scope(s) it requires. The full model:

Documents

Scope	Grants
`documents:read`	List/fetch documents, PDF status, previews, creditable clients
`documents:write`	Create/update/delete a draft document (including credit notes via `docType`)
`documents:finalize`	Finalize a draft (`POST /documents/{id}/finalize`) — assigns the number, generates the signed PDF; retry PDF generation
`documents:cancel`	Cancel an issued document (`POST /documents/{id}/cancel` — creates the counter-document)
`documents:charge`	Charge a card and finalize (`/charge-and-finalize`, `/charge-split-and-finalize`, charge handshake)
`documents:share`	Send a document by email/SMS/WhatsApp or create a share link
`documents:allocate`	Request/decide a Tax Authority allocation number (מספר הקצאה) for a document

Clients & CRM

Scope	Grants
`clients:read`	List/fetch clients, find by name
`clients:write`	Create/update/delete clients, branches, contacts
`crm:read`	Read CRM data — pipelines, deals, tasks, meetings, notes, call logs, timeline
`crm:write`	Create/update CRM records
`tags:read` / `tags:write`	Read / manage tags and tag assignments
`addresses:read` / `addresses:write`	Israeli address search and saved addresses

Catalog & inventory

Scope	Grants
`products:read`	List/search/fetch your product catalog
`products:write`	Create/update/delete products, product import
`inventory:read` / `inventory:write`	Warehouses, stock levels, stock movements, counts
`suppliers:read` / `suppliers:write`	Suppliers and their expense history
`templates:read` / `templates:write`	Document template CRUD and versioning

Money & payments

Scope	Grants
`payments:read` / `payments:write`	Payment links, payment terminals, transaction fees
`mandates:read` / `mandates:write`	Standing orders (הוראות קבע) — create, pause, cancel, charge history
`payment-terms:read` / `payment-terms:write`	Payment terms configuration
`banking:read` / `banking:write`	Business bank accounts
`ledger:read` / `ledger:write`	Customer ledger — read balances/open items; post manual adjustments and opening balances

Expenses

Scope	Grants
`expenses:read` / `expenses:write`	List/create/update/delete expenses
`expenses:approve`	Approve/reject an expense
`expenses:ocr`	Run OCR on receipt images
`expenses:export`	Generate and send expense export packages

Business, reporting & platform

Scope	Grants
`business:read`	Business profile, document config/defaults, billing invoices, next document number
`business:write`	Update the business profile, logo, document config/defaults
`analytics:read`	Dashboards, business analytics, client statistics, SMS usage
`reports:read`	Financial reports — trial balance, P&L, balance sheet, cash flow
`tax:read`	VAT reports (monthly/bi-monthly), Tax Authority status
`exports:read`	Uniform export (מבנה אחיד / BKMVDATA) generation and download
`certificates:read`	Digital signing certificate status/history
`projects:read` / `projects:write`	Projects and scheduling
`notifications:read` / `notifications:manage`	Read / mark / delete in-app notifications, preferences
`webhooks:manage`	Create, list, update, delete, and test webhook endpoints

Request the minimal set your integration actually needs — an OAuth consent screen shows the merchant exactly what you're asking for, and a narrower API key limits the blast radius if it ever leaks.

Missing a scope

A request with an insufficient scope gets 403:

{
  "error": "insufficient_scope",
  "message": "Missing required scopes: documents:write",
  "requiredScopes": ["documents:write"],
  "grantedScopes": ["documents:read", "clients:read"]
}

Older API keys created before this scope model existed may still carry legacy short scope names (read, write, documents, clients, webhooks, expenses, reports). Those are checked literally and do not satisfy the canonical documents:write-style checks above — re-issue the key with canonical scopes if it needs to call a public-API-accessible route.

On this page