Scopes & permissions
The OAuth consent scope catalog, how it maps to the fine-grained scopes tools enforce, the super-scope, and plan/module gating.
Every MCP tool declares the scope a credential must hold to call it. Scopes work slightly differently per channel:
- API keys are created directly with fine-grained scopes
(
resource:action, e.g.invoices:read) — the same closed catalog the REST API uses. You can also grant the super-scope*. - OAuth tokens are granted dotted scopes (
resource.action, e.g.invoices.read) on the consent screen. The server translates these to the fine-grained scopes automatically, so both channels enforce the same set at the tool boundary.
OAuth consent catalog
These are the scopes a user can grant a third-party app on the consent screen. There are 59 simple scopes plus 3 macros.
Simple scopes
Each grants one capability. The Maps to column shows the fine-grained scope the tools enforce — the consent layer translates dotted OAuth scopes to these automatically. The Sensitive column marks scopes the consent screen flags and does not pre-check.
Profile
| Scope | Grants | Maps to | Sensitive |
|---|---|---|---|
profile.read | Read your name, email and active company. | account:read | no |
CRM — clients & suppliers
| Scope | Grants | Maps to | Sensitive |
|---|---|---|---|
clients.read | List and read clients. | clients:read | no |
clients.write | Create and update clients. | clients:write | no |
clients.delete | Delete clients. | clients:delete | ⚠ yes |
suppliers.read | List and read suppliers. | suppliers:read | no |
suppliers.write | Create and update suppliers. | suppliers:write | no |
suppliers.delete | Delete suppliers. | suppliers:delete | ⚠ yes |
Catalog — products, series, taxes
| Scope | Grants | Maps to | Sensitive |
|---|---|---|---|
products.read | List and read the product catalog. | products:read | no |
products.write | Create and update products. | products:write | no |
products.delete | Delete products. | products:delete | ⚠ yes |
series.read | Read numbering series. | series:read | no |
series.write | Create and update numbering series. | series:write | no |
taxes.read | Read tax rates and retentions. | taxes:read | no |
taxes.write | Create and update tax rates. | taxes:write | no |
Sales — invoices, quotes, pro-formas, delivery notes
| Scope | Grants | Maps to | Sensitive |
|---|---|---|---|
invoices.read | List and read invoices. | invoices:read | no |
invoices.write | Create and update invoices. | invoices:write | no |
invoices.send | Send invoices by email. | invoices:send | no |
invoices.delete | Delete draft invoices. | invoices:delete | ⚠ yes |
invoices.annul | Annul issued invoices. | invoices:void | ⚠ yes |
invoices.create_corrective | Issue corrective invoices. | invoices:write | no |
quotes.read | List and read quotes. | quotes:read | no |
quotes.write | Create and update quotes. | quotes:write | no |
quotes.send | Send quotes by email. | quotes:send | no |
quotes.delete | Delete quotes. | quotes:delete | ⚠ yes |
quotes.convert_to_invoice | Accept/reject and convert quotes to invoices. | quotes:transition | no |
proformas.read | List and read pro-forma invoices. | proformas:read | no |
proformas.write | Create and update pro-formas. | proformas:write | no |
proformas.send | Send pro-formas by email. | proformas:send | no |
proformas.delete | Delete pro-formas. | proformas:delete | ⚠ yes |
proformas.convert | Convert pro-formas to invoices. | proformas:transition | no |
delivery_notes.read | List and read delivery notes. | delivery_notes:read | no |
delivery_notes.write | Create, update and send delivery notes. | delivery_notes:write | no |
delivery_notes.send | Send delivery notes by email. | delivery_notes:write | no |
delivery_notes.delete | Delete delivery notes. | delivery_notes:delete | ⚠ yes |
delivery_notes.convert | Convert delivery notes. | delivery_notes:transition | no |
delivery_notes.sign | Mark delivered / sign delivery notes. | delivery_notes:transition | ⚠ yes |
Purchases
| Scope | Grants | Maps to | Sensitive |
|---|---|---|---|
purchase_invoices.read | List and read vendor bills. | purchase_invoices:read | no |
purchase_invoices.write | Create and update vendor bills. | purchase_invoices:write | no |
purchase_invoices.mark_paid | Mark vendor bills as paid. | purchase_invoices:transition | ⚠ yes |
purchase_invoices.delete | Delete vendor bills. | purchase_invoices:delete | ⚠ yes |
Payment scopes are asymmetric across sales and purchases. Registering a
payment on a sales invoice (register_invoice_payment) needs
invoices:write — it edits the invoice. Registering a payment on a
purchase invoice (register_purchase_invoice_payment) needs
purchase_invoices:transition instead, because on the buy side a payment moves
the bill through its lifecycle (pending → paid) rather than editing it.
Recurring invoices
| Scope | Grants | Maps to | Sensitive |
|---|---|---|---|
recurring.read | List and read recurring templates. | recurring_invoices:read | no |
recurring.write | Create and update recurring templates. | recurring_invoices:write | no |
recurring.pause | Pause recurring templates. | recurring_invoices:transition | no |
recurring.resume | Resume recurring templates. | recurring_invoices:transition | no |
recurring.generate_now | Emit a recurring invoice manually. | recurring_invoices:transition | ⚠ yes |
recurring.delete | Delete recurring templates. | recurring_invoices:delete | ⚠ yes |
Compliance (VeriFactu)
| Scope | Grants | Maps to | Sensitive |
|---|---|---|---|
verifactu.read | Read VeriFactu records, events, certificates and config. | verifactu:read | no |
Webhooks
| Scope | Grants | Maps to | Sensitive |
|---|---|---|---|
webhooks.read | List webhook endpoints and deliveries. | webhooks:read | no |
webhooks.write | Create, update, rotate and ping webhook endpoints. | webhooks:write | ⚠ yes |
webhooks.delete | Delete webhook endpoints. | webhooks:delete | ⚠ yes |
Workforce — control horario
Employee, time-tracking, absence, work-schedule, presence, holiday and
payroll-export data. Every workforce scope is sensitive (employee PII and
compliance data) and requires the control_horario plan module — see
Plan & module gating. Reads, employees.write and
payroll-export generation are grantable on the consent screen; the privileged
write and transition actions have no OAuth dotted scope and are API-key-only
(listed under the fine-grained scopes below).
| Scope | Grants | Maps to | Sensitive |
|---|---|---|---|
employees.read | List and read employees. | employees:read | ⚠ yes |
employees.write | Create and update employees. | employees:write | ⚠ yes |
time_entries.read | Read time-clock entries, balances and monthly time sheets. | time_entries:read | ⚠ yes |
absences.read | List and read absences, policies and requests. | absences:read | ⚠ yes |
work_schedules.read | Read work schedules and their assignments. | work_schedules:read | ⚠ yes |
presence.read | Read live and daily presence. | presence:read | ⚠ yes |
holidays.read | Read the company holiday calendar. | holidays:read | ⚠ yes |
payroll_exports.read | Read generated payroll exports. | payroll_exports:read | ⚠ yes |
payroll_exports.write | Generate payroll exports. | payroll_exports:write | ⚠ yes |
Macro scopes
Convenience bundles that expand to a list of simple scopes at token-issue time. The token persists the expanded scopes — macros are never stored.
| Macro | Grants | Sensitive |
|---|---|---|
factuarea.read | Full read access to everything (no writes). | no |
factuarea.write | Read everything, plus create/update documents and send emails. | no |
factuarea.full | Read, write, send and destructive actions (delete, annul, mark paid, sign). Excludes VeriFactu writes. | ⚠ yes |
The super-scope *
A credential holding * covers every scope — all 391 tools for an API key.
It's the equivalent of an owner key. Reserve it for one-off migrations or
fully-trusted owner automations; prefer the narrowest scope set for everything
else. The super-scope is available to API keys; OAuth consent grants explicit
scopes (or macros), never a raw *.
How OAuth scopes become fine scopes
When an OAuth token is issued, its dotted scopes are translated once to the fine-grained catalog the tools enforce. A few reconciliations are worth knowing:
recurring.*maps to therecurring_invoices:*resource.invoices.create_correctivemaps toinvoices:write(creating is a write).invoices.annulmaps toinvoices:void.- Lifecycle actions (
*.convert,*.sign,*.pause,*.resume,*.generate_now,*.mark_paid,quotes.convert_to_invoice) map to the resource's:transitionscope. - Any read scope on a document also grants the transversal read utilities
pdfs:read(download its PDF/receipt) andevents:read(its activity log). verifactu.writeanddelivery_notes:gdpr_forgethave no OAuth dotted scope — they are unreachable via OAuth by design.facturae:read/facturae:writeare not in the OAuth consent catalog yet — the FacturaE (FACe) tools are reachable only with an API key for now.
Fine-grained scopes without an OAuth scope (API key only)
A few fine-grained scopes live in the closed resource:action catalog API keys
use, but have no dotted OAuth equivalent — they are never granted through a
third-party consent screen and are reachable only with an API key. Grant them on
the key directly (or via the super-scope *). Some are gated by an integration
module — the key's company must then hold the corresponding plan (see
Plan & module gating); the rest are first-party
account and gestoría scopes.
| Scope | Grants | Module gate |
|---|---|---|
stripe_autoinvoicing:read | Read the Stripe Connect integration status, auto-invoicing config and connected accounts, and list auto-invoiced charges/correctives. | integration_stripe |
stripe_autoinvoicing:write | Toggle Stripe charge auto-invoicing, set the auto-issued series, and edit/disconnect connected accounts. | integration_stripe |
payouts:read | Read ingested Stripe payouts and their bank-reconciliation status. | integration_stripe |
These power the Payments & gateways tools.
A second group of API-key-only scopes governs first-party account and
gestoría management — your own credentials and, for accountancies, the child
sub-companies you manage and their API keys. companies:* requires the gestoría
plan module; the rest have no module gate.
| Scope | Grants | Module gate |
|---|---|---|
account:write | Manage your own API keys (create, rotate, revoke) and update account personalization. | — |
companies:read | List and read managed companies (child sub-accounts). | gestoria |
companies:write | Create, update, activate and deactivate managed companies. | gestoria |
companies:delete | Archive managed companies. | gestoria |
api_keys:read | List and read API keys of managed companies. | — |
api_keys:write | Create, rotate and revoke API keys of managed companies. | — |
api_keys:delete | Permanently delete API keys of managed companies. | — |
A third group covers workforce (control horario) write and transition
actions. Their read counterparts are OAuth-grantable (see the Workforce consent
scopes above), but these privileged scopes have no OAuth dotted equivalent — they
are API-key-only, the mirror of verifactu:write. All require the
control_horario plan module.
| Scope | Grants | Module gate |
|---|---|---|
employees:delete | Permanently delete employees. | control_horario |
time_entries:write | Clock in/out, record manual entries, manage time corrections and the monthly register close. | control_horario |
absences:write | Create and manage absence types, policies and requests. | control_horario |
absences:transition | Approve, reject and cancel absence requests. | control_horario |
work_schedules:write | Create, update, assign and archive work schedules. | control_horario |
verifactu:write, facturae:read, facturae:write and
delivery_notes:gdpr_forget are also fine-grained, API-key-only scopes
(covered above) — they enforce at the tool boundary just like any other scope,
but have no OAuth consent counterpart.
Plan & module gating
Most published tools apply only a scope check — they're reachable as soon as
the credential holds the required scope. Two families are also module-gated.
The Payments & gateways tools map their scopes
(stripe_autoinvoicing:*, payouts:read) to the integration_stripe module.
The workforce tools (Employees, Employee seats, Work schedules, Time tracking,
Absences, Presence, Holidays) map their scopes (employees:*, time_entries:*,
absences:*, work_schedules:*, presence:read, holidays:read,
payroll_exports:*) to the control_horario module. When the company's plan
lacks the module, the server hides those tools from tools/list and returns
module_not_in_plan (-32005) on a direct call.
- Plan usage limits (e.g. monthly document quotas) are enforced at call time
and surface as
plan_limit_exceeded(-32004). See Errors & rate limits.
The whole public MCP surface also requires the company to have an active
Factuarea plan — API access is included in every plan; otherwise every call
returns addon_not_active (-32007).