Scopes reference

Every scope a key, connected app or agent can hold, what each one allows, and the rules that keep a scope from ever granting more than the person or role behind it.

Updated in release 0.0.1

A grant names what a credential may do. It narrows, never widens: a token only ever gets the intersection of its grant and what its principal (the person, the integration user or the agent) is allowed to do by their roles.

What a credential can be granted

Nova grants permission keys — the same names its own routes check. A scope in the list below is a shortcut for a set of them, so an app can ask for something short and a person can read what they are allowing. You can also ask for a single permission key by name; both forms work anywhere a scope is accepted.

Scope	Allows	Permissions
`accounts:read`	Read customers, leads, contacts and addresses	11
`accounts:write`	Add and change customers, leads, contacts and addresses	41
`notes:read`	Read notes on records	12
`notes:write`	Add and edit notes on records	107
`files:read`	List and download files attached to records	61
`files:write`	Upload and organize files on records	250
`quotes:read`	Read quotes	2
`quotes:write`	Create, update and finish quotes	16
`invoices:read`	Read invoices	5
`invoices:write`	Create, update and finish invoices	20
`payments:read`	Read recorded payments	2
`payments:write`	Record payments the customer already made	10
`work_orders:read`	Read work orders and the schedule	37
`work_orders:write`	Create, update and schedule work orders	116
`tasks:read`	Read tasks and comments	3
`tasks:write`	Create and update tasks and comments	20
`projects:read`	Read projects	2
`projects:write`	Create and update projects	11
`bookings:read`	Read bookings	7
`bookings:write`	Create, update and cancel bookings	32
`tickets:read`	Read customer tickets	14
`tickets:write`	Create and update customer tickets	38
`organization:read`	Read your organization and its branches	35
`help:read`	Search and read Nova help articles	1
<!-- /generated:bundles -->

Nova has 2186 permissions across 670 kinds of record.

2025 can be granted to software — everything your organization itself can do, including deletes, voids and settings.
161 cannot, because they are not your organization's to hand out: Nova platform administration, the enterprise hub, and a person's own profile settings.

Two things make a call wait for a person. Actions you name under Ask a person first on the credential itself, and the few actions Nova always protects with an identity check (payout accounts, role changes and member removal, bulk exports, privacy requests), which software can never pass on its own.

Some operations need two scopes, for example converting a quote into an invoice needs quotes:write and invoices:write. The reference lists the exact scopes under each operation.

Rules

Read scopes only grant read-like permissions. A :read scope never unlocks a create, update, send or delete.
A grant can carry anything your organization can do, deletes and voids and settings included. The limit is the person who created the credential: a grant is refused, naming the permission, if it reaches past what they hold themselves. Pick a bundle plus the individual keys you need.
Approvals are yours to choose, plus a short fixed list. List permissions under Ask a person first on an API key or an AI teammate, and each use goes to Approvals instead of running straight away. Actions Nova guards with an identity check for a person (payout accounts, role changes, bulk exports and the like) always go to Approvals when software tries them. See Handle an action that waits for a person's approval.
No scopes means nothing. A key or agent created with an empty scope list cannot call anything; there is no "all scopes" fallback.
Refresh may narrow, never widen. A refresh request may ask for a subset of the scopes originally granted, never for more.
One organization per token. A machine token is bound to the organization it was created in; sending a different X-Organization-ID is refused.

Asking for scopes

Connected apps request scopes as a space-separated scope parameter on the authorize request. The person can untick any of them on the Connect an app page, so read the scope in the token response rather than assuming you got everything you asked for. Agents and API keys get their scopes from the admin who created them.

Was this helpful?