Scopes & permissions

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 *, which does not cover the two privileged scopes.
• 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 79 simple scopes plus 3 macros. Consent grants the business data of one tax ID and never the administration of the account: the keys, the team, the ownership, the tax ID transfers, the tax ID portfolio and the accounts you provision have no scope here and need an API key (see the scopes without an OAuth scope). One of the 79, payroll_exports.write, is in the catalog but the screen does not offer it, because no tool requires the scope it translates to.

What the screen grants by level and environment

The screen does not offer every scope in every case, and the confirmation checks it again on the server:

• View level. If you reach the company with View access, only read scopes can be granted: those ending in .read and the factuarea.read macro. Confirming a write scope answers 403 invalid_scope with read_only_restricted_scopes, which lists the rejected scopes.
• Test environment. The sandbox does not offer some modules: VeriFactu, the WhatsApp assistant, the document Vault, the Stripe, GoCardless, Monei, Slack and Teams integrations, webhooks and task integrations. Their scopes are not granted in Test; the confirmation answers 403 with sandbox_restricted_scopes.
• Expiry. The consent request expires 5 minutes after it opens, and the screen shows how many minutes are left.

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

Contacts

Catalog — products, price lists, series, taxes

Sales — invoices, quotes, pro-formas, delivery notes, transport control documents

PDF templates

The company's PDF template library: templates, brands (commercial identities), private assets and preferences. Both scopes require the pdf_templates plan module — see Plan & module gating — and cover the PDF templates tools. None of the factuarea.* macros includes them, so an app has to ask for them explicitly. preview_pdf_template also needs pdfs:read.

Purchases

Recurring invoices

Compliance and tax reports

Webhooks

These scopes cover the webhook endpoints of a tax ID. The webhook tools of the account reuse the same fine-grained scopes but consent never reaches them: see account tools that share a scope with a tax ID.

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 and employees.write are grantable on the consent screen, payroll_exports.write is not offered, and the privileged write and transition actions have no OAuth dotted scope and are API-key-only (listed under the fine-grained scopes below).

Automations

Automation rules and their run history. Every automation scope is sensitive: a rule can send emails and fire webhooks on the account owner's behalf, and the run history carries the business payloads its actions moved (amounts, recipients, outcomes). All three require the automations plan module — see Plan & module gating. Reading and writing rules and reading the run history are grantable on the consent screen; deleting a rule is not — automations:delete has no OAuth dotted scope and is API-key-only (listed under the fine-grained scopes below).

automations.read and automation_runs.read are granted separately on purpose. The first one covers the rule book: the rules themselves, their sealed versions, the trigger/action catalog and the dry run that reports what a rule would do without doing it. The second one covers what the rules actually did: every run, its steps, their typed discard reasons and the frozen trigger payload each run carries. An app can read which automations exist without reading the business data every execution touched.

Projects and tasks

Task projects, tasks and their surroundings. projects.* and tasks.* require the tasks plan module — see Plan & module gating —, while users.read and notifications.* are cross-cutting and belong to no module. projects.write and tasks.write are sensitive: an app can create, move and comment on tasks and log time on the account owner's behalf. users.read is also sensitive: it exposes the whole directory of the company, emails included. Reading and writing are grantable on the consent screen; deleting is not — projects:delete and tasks:delete have no OAuth dotted scope and are API-key-only (listed under the fine-grained scopes below).

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.

The super-scope *

A credential holding * covers every scope except the two privileged ones, accounts:read and accounts:write — all 668 tools of the catalog 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 *.

A key that holds only * does not reach the ten managed-account tools: they need accounts:read or accounts:write listed on the key, and the account has to hold the privilege.

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 the recurring_invoices:* resource.
• invoices.create_corrective maps to invoices:write (creating is a write).
• invoices.annul maps to invoices:void.
• Lifecycle actions (*.convert, *.sign, *.pause, *.resume, *.generate_now, *.mark_paid, quotes.convert_to_invoice) map to the resource's :transition scope.
• Any read scope on a document also grants the transversal read utilities pdfs:read (download its PDF/receipt) and events:read (its activity log).
• pdf_templates.read and pdf_templates.write map to pdf_templates:read and pdf_templates:write. They grant no pdfs:read: the PDF artifact tools get it from a document read scope, as in the previous bullet.
• verifactu.write and delivery_notes:gdpr_forget have no OAuth dotted scope — they are unreachable via OAuth by design.
• The scopes of the account — account:write, account:owner, members:*, invitations:*, nif_transfers:*, companies:* and the privileged accounts:* — have none either. profile.read is the only account scope that consent translates, and it gives account:read.

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 *, except for accounts:*). 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 scopes of the account.

These power the Payments & gateways tools.

A second group of API-key-only scopes governs what the account itself holds: its keys, its team, its ownership and its tax ID transfers. account:read is the only account scope that consent reaches, through profile.read. These are not privileged, so the super-scope * does cover them. The members:*, invitations:* and nif_transfers:* scopes need the user_management module: on a plan without it they cannot be assigned to a key (see Plan & module gating).

How the grants of a member work on a tax ID of another account is in granted access.

A third group governs the tax ID portfolio of the account. Any account, on any plan, lists and reads its own tax IDs, so companies:* has no module gate. What the plan gates is adding a tax ID that the account pays for, and it does so inside the operation, not in the scope: see additional tax IDs.

A fourth 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.

A fifth group is the automation engine's delete scope. Its three siblings — automations.read, automations.write and automation_runs.read — are OAuth-grantable (see the Automations consent scopes above), but removing someone's automation is destructive and cannot be undone through the API, so it stays out of the consent catalog by design — the same call made for verifactu:write. It requires the automations plan module.

A fifth group is the task module's delete scopes. Their siblings — projects.read|write and tasks.read|write — are OAuth-grantable (see the Projects and tasks consent scopes above), but deleting a project or a task takes its comments, attachments and logged time with it and cannot be undone through the API, so both stay out of the consent catalog by design — the same call made for automations:delete. They require the tasks plan module.

A final group covers the remaining first-party observability tools and the scopes that the closed catalog reserves, none of which has a dotted OAuth consent scope:

Privileged scopes

Two scopes are privileged: accounts:read and accounts:write. They let an account provision, administer and charge the accounts of its clients, and the ten managed-account tools need them. They differ from every other scope:

• The super-scope * does not cover them. List them on the key, next to * if you also want the rest of the account.
• Factuarea grants them, account by account. You cannot assign them to yourself: the API has no operation that grants the privilege, and creating a key that lists them without it answers 403 privileged_scope_required. GET /v1/me tells you whether your account holds it, in account.is_provider and account.privileged_scopes.
• They are checked on every call. The key must list the scope, your account must hold the privilege today and the person who issued the key must still be an owner or an admin of the account. If any of the three fails the answer is 403 privileged_scope_required, and both causes answer alike. Nothing comes from a cache, so a revoked privilege stops the same key on its next call.
• Consent never grants them and no module of the plan gates them: the gate is the privilege. They need an API key.

The bulk import needs the same scopes and has no MCP tool: see what the MCP server does not carry.

Account tools that share a scope with a tax ID

Ten tools administer the webhook endpoints of the account and two read its API request logs. They reuse webhooks:read, webhooks:write, webhooks:delete and developers:read, the scopes that the tools of a tax ID already use, so the scope alone does not tell them apart. The channel does:

OAuth does not reach them even when it holds the scope: tools/list does not announce them to an OAuth connection, and a direct call answers 403 forbidden_action. The webhook tools of a tax ID keep their consent scopes.

With an API key, each call checks first that the account of the credential is reachable (404 account_not_found), then, for a tool that writes, that the key is live (403 live_credential_required with a test key), and finally that the person who issued the key is today an owner or an admin of the account and that the scope of the key covers every real tax ID of the account (403 forbidden_action, the same answer for both causes). The payer tier of the account also caps the endpoints: a tier without account webhooks answers 402 addon_required, and a full one 422 account_webhook_endpoint_limit_reached. Account webhooks describes each check.

Plan & module gating

Most published tools apply only a scope check — they're reachable as soon as the credential holds the required scope. Several families are also module-gated. The Price-list tools map price_lists:* to products. The Payments & gateways tools map their scopes (stripe_autoinvoicing:*, payouts:read, integration_events:*) 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. The Automations tools map their scopes (automations:*, automation_runs:read) to the automations module. The team and transfer scopes (members:*, invitations:*, nif_transfers:*) map to the user_management module, which the empresario and enterprise plans include. The Projects and Tasks tools map projects:* and tasks:* to the tasks module, which every plan includes; users:read and notifications:* belong to no module. The PDF templates tools map pdf_templates:* to the pdf_templates module, and the FacturaE (FACe) tools require the facturae 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.

• Some scopes have no module gate, on purpose. accounts:* are gated by the privilege of the account, not by the plan. companies:* let any account, on any plan, list and read its own tax IDs: the plan gates the purchase of an additional tax ID inside the operation (additional tax IDs), not the scope, so the tax ID portfolio does not depend on a plan module. account:* are operations of the account on itself and have none either.
• 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).

Store permissions

Store management uses stores:read and stores:write; provider-specific scopes are woocommerce_store:read, woocommerce_store:write, shopify_store:read and shopify_store:write. Connection-test operations require the provider write scope. These scopes are assigned to API keys and are outside OAuth consent. See ecommerce stores for the operation matrix.