Authentication

The Factuarea API authenticates every request with an API key. Keys are opaque tokens generated in the developer dashboard (app.factuarea.com/settings/developers/api-keys) and bound to a specific company. 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 company (production); fact_test_ operates on an isolated sandbox company 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. If you lose it, you must rotate.
• DB hash: the backend stores only the bcrypt cost-12 hash of 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/contacts \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

X-API-Key header

curl https://api.factuarea.com/v1/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('contacts?limit=10');
$body = json_decode((string) $response->getBody(), true);

const res = await fetch('https://api.factuarea.com/v1/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/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. OAuth consent exposes 68 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.

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 raises invalid_scope 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.

Clients and catalog

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.

Managed companies (gestoría)

Fine-grained scopes for the gestoría model, where a master account manages child sub-companies and their API keys. Reachable only with an API key (no OAuth consent equivalent); companies:* also requires the gestoría plan module.

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": "La API key no tiene el scope requerido para esta operación.",
    "request_id": "req_01JBVH7..."
  }
}

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; the dashboard also configures the IP allowlist.

The authenticated key's metadata (id, name, prefix, scopes, tier, last_used_at, expires_at) is readable via GET /v1/account — 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.
• 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 company (tenant) and 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. If the request comes from an IP outside the allowlist, the response is 401 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 for insufficient_scope) 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.
• 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.