Authentication

The Factuarea API authenticates every request with an API key. Keys are opaque tokens issued by an owner or an admin of the account in the developer dashboard (app.factuarea.com/settings/developers/api-keys), or through the self-service v1 endpoints. A key belongs to an account, never to one tax ID. Its reach is its scope: the tax IDs assigned to it, which can be tax IDs of the account and tax IDs of another account that lets you reach them. Every tax ID route names the one it operates on in its own path (/v1/companies/{company}/…), and every account route names your account (/v1/accounts/{account}/…). GET /v1/me enumerates the scope — one entry per tax ID, with the opaque id the path expects and its tax_id — so a credential never has to guess which tax IDs it reaches. Every request to https://api.factuarea.com/v1/* must include a valid key in one of the two supported formats.

API key format

fact_live_<24 alphanumeric characters>
fact_test_<24 alphanumeric characters>

Example:

fact_live_8KqW3pXnR2VbY7TcA9eFmN5z
fact_test_3pXnR2VbY7TcA9eFmN5z8KqW

• Prefix: determines the environment. fact_live_ operates on your real tax IDs (production); fact_test_ reaches only the isolated sandbox company of your account, with external effects (VeriFactu → AEAT, FACe, emails, webhooks) switched off. The prefix lets you identify the environment without decoding the key. See Test mode & sandbox.
• Secret: 24 base62 characters → ~143 bits of entropy. Shown only once at creation, in the dashboard or in the API response. If you lose it, you must rotate.
• Storage: the backend stores only a keyed hash (HMAC-SHA256) of the secret, never the secret. There's no way to recover it.

Sending the key on each request

The API accepts two equivalent formats. Pick the one that fits your client:

Authorization Bearer (recommended)

curl https://api.factuarea.com/v1/companies/{company}/contacts \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

X-API-Key header

curl https://api.factuarea.com/v1/companies/{company}/contacts \
  -H "X-API-Key: fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

Send only one of the two headers. If both are present, the Authorization: Bearer header takes precedence.

Examples per language

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.factuarea.com/v1/',
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('FACTUAREA_API_KEY'),
        'Accept' => 'application/json',
    ],
]);

$response = $client->get('companies/{company}/contacts?limit=10');
$body = json_decode((string) $response->getBody(), true);

const res = await fetch('https://api.factuarea.com/v1/companies/{company}/contacts?limit=10', {
  headers: {
    Authorization: `Bearer ${process.env.FACTUAREA_API_KEY}`,
    Accept: 'application/json',
  },
});
const data = await res.json();

import os
import requests

resp = requests.get(
    'https://api.factuarea.com/v1/companies/{company}/contacts',
    params={'limit': 10},
    headers={
        'Authorization': f"Bearer {os.environ['FACTUAREA_API_KEY']}",
        'Accept': 'application/json',
    },
)
resp.raise_for_status()
data = resp.json()

OAuth 2.1

For agent integrations and third-party apps that act on behalf of a Factuarea user, the API also supports the OAuth 2.1 authorization-code flow with PKCE (code_challenge_method=S256) as an alternative to a static API key. The OAuth consent catalog has 73 simple dotted scopes plus the factuarea.read, factuarea.write and factuarea.full macros; they are mapped to the fine-grained colon scopes that gate each endpoint and MCP tool. The rotation policy applies to OAuth client secrets too.

The consent catalog includes price_lists.read/write, facturae.read/write and tax_reports.read/write. The screen offers only the scopes requested by the client, never pre-selects sensitive scopes, and the issued token contains exactly the subset the user approved. One scope of the catalog, payroll_exports.write, is not offered, because no tool requires the scope it translates to.

What OAuth consent reaches

Consent grants the business data of a tax ID and never the administration of the account. A fine-grained scope is out of reach when the catalog has no dotted scope that translates to it, and these ones are excluded on purpose, so that an app of a third party can never obtain them whatever the user approves:

Everything else that the catalog translates is reachable: contacts, the catalog, sales documents, purchases and recurring invoices, tax reports, FacturaE, VeriFactu reads, webhooks, automations and workforce reads, and account:read through profile.read. Some operations stay out of OAuth even though their scope is reachable, such as the webhooks and the request logs of the account: MCP tools shows the channel of each tool. Use an API key for every excluded scope, also with the MCP server. MCP scopes lists the consent catalog.

Discovery metadata (RFC 8414) is published at /.well-known/oauth-authorization-server, so OAuth clients can resolve the authorization and token endpoints automatically:

curl https://api.factuarea.com/.well-known/oauth-authorization-server

The OAuth2 security scheme — including the authorization and token URLs and the full scope list — is described in the API Reference.

Scopes

Each API key is created with one or more scopes that limit which endpoints it can invoke. Scopes are strings of the form <resource>:<action>. The catalog is closed: any scope outside the listed set fails validation with 422 invalid_param_value when creating the key.

The valid catalog is append-only for existing credentials, while the subset assignable to a new key follows the currently released API surface. The four reserved GoCardless/MONEI scopes below remain recognizable for historical compatibility, but are omitted from CreateApiKeyV1Request and cannot be assigned until those providers are released. Plan and sandbox restrictions are then enforced separately with scope_not_allowed_by_plan and scope_not_allowed_in_sandbox: a scope is granted only if the plan of every tax ID in the scope of the key allows it.

Contacts and catalog

A customer and a supplier are two roles of the same identity — the contact — so a single trio of scopes covers both. The former clients:* and suppliers:* scopes are retired and no longer assignable.

Sales documents

Purchases and recurring

Catalogs and export

VeriFactu & FacturaE

Webhooks and events

Integrations and observability

Workforce (control horario)

These scopes require the control_horario plan module. Some read scopes are OAuth-grantable; privileged writes and transitions remain API-key-only.

Tasks & projects

projects:* and tasks:* require the tasks module, which every plan includes; users:read and notifications:* are cross-cutting. The projects:delete and tasks:delete scopes are API-key-only: an OAuth consent never grants them. Invoicing the hours of a project also needs invoices:write. See Projects and tasks.

Tax ID portfolio

Fine-grained scopes for the tax IDs that your account holds. They work on /v1/accounts/{account}/companies… and need an API key: consent never grants them. Any account, on any plan, lists and reads its own tax IDs, so companies:* has no plan gate. What the plan gates is adding a tax ID that the account pays for, and it does so inside the operation (additional tax IDs).

Tax ID portfolio describes the operations.

Account administration

Scopes for what the account itself holds: its keys, its team and its ownership. They need an API key, except account:read, which OAuth consent grants through profile.read. They are not privileged, so the super-scope * does cover them.

GET /v1/me needs no scope: any valid credential can introspect itself. On a plan without the user_management module the members:*, invitations:* and nif_transfers:* scopes cannot be assigned to a key, and GET /v1/me lists only the effective ones. The empresario and enterprise plans include the module.

API keys are not managed with api_keys:*. The six endpoints under /v1/accounts/{account}/api-keys are governed by account:read (list and retrieve) and account:write (create, change the tax IDs of, rotate the secret and revoke) — see API keys and scoped keys. Accounts and tax IDs describes the team and the transfers.

Privileged scopes

Two scopes are privileged: accounts:read and accounts:write. They let an account provision, administer and charge accounts for its clients, which managed accounts describes. They differ from every other scope:

• Factuarea grants them, account by account. Only Factuarea can: the API has no operation that grants the privilege. GET /v1/me tells you whether your account holds it, in account.is_provider and account.privileged_scopes. You cannot assign them to yourself: creating a key that lists them without the privilege answers 403 privileged_scope_required and creates nothing.
• They are checked on every request. 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 your account. If any of the three fails the answer is 403 privileged_scope_required, and both causes answer alike. Nothing comes from a cache: if we revoke the privilege, or that person stops being an owner or an admin, the same key stops working on its next request.
• They do not come through OAuth. Consent never grants them: use an API key, also with the MCP server.
• No plan gates them. The gate is the privilege, not the plan.
• * does not cover them. See the super-scope.

Super-scope

If a request uses an endpoint that requires a scope not granted to the key, the response is 403 with type: authorization_error and code: insufficient_scope.

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'account:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01JBVH7K9Y4N3CDQ2EHJB1AGSV"
  }
}

Key management

API keys can be managed from the developer dashboard (app.factuarea.com/settings/developers/api-keys) or through the self-service v1 endpoints. Both surfaces let you create, rotate and revoke keys and set the IP allowlist when you create one; the dashboard also edits it afterwards. The dashboard is for the owners and the admins of the account, and the keys that you issue never reach more than you do: who can issue a key explains it.

The authenticated key's metadata (id, name, prefix, scopes, tier, environment, last_used_at, expires_at) is readable via GET /v1/me, alongside the tax IDs the key reaches — but the secret is never returned.

Rotation policy

API keys and OAuth client secrets are long-lived credentials and must be rotated on a schedule and immediately after any suspected leak.

• Prefixes are the source of truth for the environment: fact_live_ (production) and fact_test_ (sandbox). Never mix them across environments.
• Rotate from the dashboard (or via the self-service account:write endpoints) to issue a brand-new secret. The new secret is returned once — store it immediately, it is never shown again.
• Grace window (dual-secret). After a rotation the previous secret keeps working for a 24-hour grace window, so you can roll out the new secret with zero downtime. During that window both the new and the previous secret are accepted; once the window expires the previous secret is rejected and purged. A request still using the previous secret receives a 199 Warning header telling you how many hours remain before it stops working.
• When to rotate: on a regular schedule (e.g. every 90 days), whenever a teammate with access leaves, and immediately if a secret is ever exposed in logs, source control or a public client. Rotation leaves the previous secret valid for the 24-hour grace window, so to cut an exposed secret off at once, revoke the key instead (revocation is immediate) and issue a new one.
• Revoke to invalidate a key permanently. Any subsequent request with it fails with 401. Revocation has no grace window — it is instant and irreversible.

Secrets are bound to a single account and reach only the tax IDs in their scope; they must never be embedded in browsers, mobile apps or any public client — keep them server-side only.

IP allowlist

Each API key can be restricted to a list of IPs or CIDR ranges, from the dashboard or with ip_allowlist when you create the key. If the request comes from an IP outside the allowlist, the response is 401 with the code ip_not_allowed and the incident is recorded in the audit log. Leave the allowlist empty to allow any IP.

Authentication errors

Failures related to the API key respond with HTTP 401 (or 403 when the key authenticates but is not enough) and the standard error envelope. The code field distinguishes the case:

Every response includes a unique request_id (also in the X-Request-Id header) you can pass to support when investigating.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La API key proporcionada no es válida.",
    "request_id": "req_01JBVH7K9Y4N3CDQ2EHJB1AGSV",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_api_key"
  }
}

Best practices

• Never commit API keys to repositories — use environment variables or a secret manager (AWS Secrets Manager, Doppler, 1Password Service Accounts).
• Create one key per integration: makes rotating and auditing access easier without affecting the rest.
• Limit scopes to the minimum required. An export script only needs specific :read scopes, and a key that carries only :read scopes needs just view on its tax IDs.
• Give each key only the tax IDs it needs, with scoped_company_ids (scoped keys).
• Enable IP allowlist for server-to-server integrations with stable IPs.
• Configure expires_at for temporary keys (e.g. consultancies, demos).
• Audit usage from the dashboard: Developers > API Keys > Activity shows IPs, paths and errors per key.

Credentials for integrations

Store REST and MCP operations require an API key with the store scopes. OAuth consent does not grant these scopes. Authorize the provider connection separately: a Factuarea key is not a WooCommerce or Shopify credential. MCP authentication also requires a client compatible with revision 2026-07-28.