---
key: api-scopes-reference
title: Scopes reference
audience: developer
section: api/authentication
routes: []
since: 0.0.1
updated: 0.0.1
status: published
summary: "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."
keywords: [scopes, permissions, read, write, least privilege, oauth scope list]
related: [api-authentication, choose-an-api-key-or-a-connected-app, api-reference]
---

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.

<!-- generated:bundles -->
| 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 -->

<!-- generated:rules -->
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.
<!-- /generated:rules -->

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 [[wait-for-a-person-to-approve]].
- **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.