Scopes and role tiers¶

A connection's effective permission is the intersection of the scopes it was granted, the granting member's live role, and the app's own capability flags (spec §4.1 step 4) — checked on every request, never cached from token issuance.

Scope	Description	Minimum granting role tier
`accounts:read`	Read chart of accounts	ADMIN, ADVISER, EDITOR, OWNER, VIEWER
`bills:read`	Read bills	ADMIN, ADVISER, EDITOR, OWNER, VIEWER
`bills:write`	Create and update bills	ADMIN, EDITOR, OWNER
`contacts:read`	Read suppliers and customers	ADMIN, ADVISER, EDITOR, OWNER, VIEWER
`credit_notes:read`	Read credit notes	ADMIN, ADVISER, EDITOR, OWNER, VIEWER
`credit_notes:write`	Push parsed credit notes	ADMIN, EDITOR, OWNER
`invoices:read`	Read sales invoices	ADMIN, ADVISER, EDITOR, OWNER, VIEWER
`invoices:write`	Push parsed sales invoices	ADMIN, EDITOR, OWNER
`migration:read`	Read migration batches and reference data	ADMIN, OWNER
`migration:write`	Submit and roll back migration batches	ADMIN, OWNER
`payroll:read`	Read pay-runs	ADMIN, OWNER
`payroll:write`	Post pay-runs and corrections	ADMIN, OWNER
`tax_rates:read`	Read tax rate configuration	ADMIN, ADVISER, EDITOR, OWNER, VIEWER
`webhooks:manage`	Manage webhook subscriptions	org (still requires org selection during consent)

Verified-only by default (staff-editable, developer.verified_only_scopes): payroll:read, payroll:write.

Restricted-capability scopes (webhooks:manage, migration:read, migration:write) additionally require the app to carry the matching can_use_webhooks/can_use_migration_api flag — shown in the portal and the docs as Restricted — by arrangement.

Naming convention — documented once¶

Scope strings use resource:verb (bills:read, invoices:write). API URL paths use hyphenated plural nouns (/api/v1/orgs/{org_id}/credit-notes). These are two independent, deliberately different conventions — a scope string is never a literal fragment of a URL path, and this is the one place that's spelled out; nothing else in these docs restates it.

Verified-only scopes can change without notice¶

Which scopes are verified-only is a staff-editable runtime setting (developer.verified_only_scopes), not a fixed list — a scope can move in or out of verified-only status at any time, without a version bump. This has a live effect, not just a consent-time one: for an unverified app, the effective scope set is recomputed on every request, and a verified-only scope is subtracted from it every time — existing access tokens that already carry the scope lose it on their very next call and start getting insufficient_scope 403s, with no separate revocation or re-consent step. Removing the scope from the verified-only setting restores it live, the same way. Verified apps are never affected by this setting. There's no contractual guarantee such a change is announced ahead of time; changes may be noted in the changelog, but don't assume today's verified-only set (above) is stable.

Restricted capabilities¶

Scopes marked Restricted — by arrangement above additionally require your app to carry a matching capability flag before they can be requested at consent or used on a request — this is separate from, and checked in addition to, the scope/role-tier table. To request access, use Verification in My Apps (https://<your LuciBook host>/developer/apps/<client_id>/verification/).