Scopes
The full OAuth / API key scope catalog, generated from the source of truth in the codebase.
Every API key and OAuth access token carries a set of scopes that determine what it can do. :write scopes always imply the matching :read scope — a key with accounting:write can also call accounting:read endpoints. An API key created with no scopes selected is a legacy "full access" key: it can call every non-restricted endpoint your account can reach, so prefer picking specific scopes for anything new. Restricted scopes are the one exception — see below.
This table is generated at build time from @repo/auth/public-api-scopes — the same module that drives the OAuth consent screen and the Settings → Developers key creator — so it can never drift out of sync with what the API actually enforces.
| Scope | Grants | Approval |
|---|---|---|
openid | Verify who you are so you can sign in. | Self-service |
entities:read | View your legal entities and income sources. | Self-service |
entities:write | Create and update your legal entities and income sources. | Self-service |
accounting:read | View invoices, quotes, counterparties, transactions, and reports. | Self-service |
accounting:write | Create and update invoices, quotes, counterparties, and transactions. | Self-service |
banking:read | View connected bank accounts and their transactions. | Self-service |
vault:read | View documents stored in your document vault. | Self-service |
vault:write | Upload and update documents in your document vault. | Self-service |
billing:read | View billing, subscription, and credits information. | Self-service |
periods:read | View accounting period status and close state. | Self-service |
hmrc:read | View HMRC filing status and submissions. Restricted — requires manual approval; HMRC compliance obligations apply. | Restricted — manual approval |
hmrc:write | Submit filings to HMRC on your behalf. Restricted — requires manual approval; HMRC compliance obligations apply. | Restricted — manual approval |
Restricted scopes
Scopes marked Restricted (hmrc:read, hmrc:write) require manual approval by ac-co.ai before they can be granted to an API key or OAuth client — including a legacy "full access" key created with no scopes selected. That kind of key never carries a restricted scope; there's no way to reach the hmrc.* group without approval. See HMRC compliance for why, and how to request access.
Checking what a request is missing
If a request is rejected for missing scope, the response tells you exactly which one was required — see Errors for the insufficient_scope response shape.