Developer essentials

Grants

The company owns its data. A grant gives a partner a set of scopes on it. The accountant uses the same API as you, with more scopes; there is no privileged path.

Scopes

Scope	Holder	Allows
origins:write	vertical	Send origins and attachments, define dimensions, name parties, supply the first interpretation of a waiting origin, reverse origins you delivered
ledger:read	vertical	Read everything; manage webhooks
settlements:write	vertical	Allocate open items explicitly
payments:write	vertical	Create and cancel payments; sandbox execution
connections:manage	vertical	Start bank connections
grants:manage	owner	Create and revoke grants
review:write	accountant	Re-interpret a posted origin; reject origins; close settlements with a residual; reverse any origin
accounts:manage	accountant	Create accounts, set party defaults
close:manage	accountant	Move the lock date, close fiscal years

Creating a company grants the creating partner origins:write, ledger:read, settlements:write, payments:write, connections:manage and grants:manage. Every endpoint in the API reference names the scope it needs.

Give a partner access

With grants:manage you can grant another partner, an accounting office for instance, scopes on a company. The grantee is identified by its partner id.

POST /v1/companies/{companyId}/grants
{ "granteeKind": "OFFICE", "granteeId": "ptn_…", "scopes": ["ledger:read", "review:write", "accounts:manage", "close:manage"] }

{ "id": "grt_…" }

granteeKind is VERTICAL, OFFICE, AGENT or OWNER; it labels the grant and does not change what the scopes allow. A partner may hold several grants on one company; the scopes add up.

DELETE /v1/companies/{companyId}/grants/{grantId}     # { ok: true }; the grantee's next request answers 404 COMPANY_NOT_FOUND

The accountant's scopes

An accounting office that holds review:write, accounts:manage and close:manage on a company does the accounting side: interprets what you left uninterpreted, corrects what was booked wrong, adds accounts, sets party defaults, moves the lock, closes the year. It does this in a Vexless control surface or through the same endpoints, under its own key and its own actors, and you observe the results as events. Accounting & reporting lists what to expect.

You may hold those scopes yourself, on companies where you are the accountant. Nothing in the API is reserved for anyone.

Extend your own grant

The same call with your own partner id adds scopes to what creation gave you. A vertical that also does its customers' bookkeeping grants itself review:write.

Errors

403 SCOPE_MISSING		The endpoint needs a scope your grant lacks; `scope` names it. On a party update, changing defaults needs `accounts:manage` even though the endpoint itself needs `origins:write`.
404 COMPANY_NOT_FOUND		No grant at all