Skip to content

The whole API (/api/v1/*) and the MCP server (/mcp) require authentication. There are two ways:

Who How MH environment
Integration Authorization: Bearer of_test_… 00 test
Integration Authorization: Bearer of_live_… 01 production
Dashboard Session cookie (/api/auth/*) The environment saved on the issuer

The remote MCP server only accepts API keys, never the dashboard cookie.

A key’s environment also separates data: it only sees the products and webhooks of its environment, and saved customers only exist in production (with a test key they respond 409 clientes_solo_produccion).

Ventana de terminal
curl https://app.openfactura.co/api/v1/yo -H "Authorization: Bearer $OPENFACTURA_API_KEY"

GET /yo tells you who you are: actor (usuario or clave), organization, permissions, and active environment. Use it to check a key.

In the dashboard: API keys → New key. Choose a name, a mode (test or production), permissions, and optionally an expiry in days. The full key is shown only once; the server stores only its SHA-256 and from then on shows just its prefix.

Keys can also be managed through the API (GET|POST /claves, DELETE /claves/:id), but only from a dashboard session with the claves:manage permission: an API key can never create other keys.

Revoking a key takes effect immediately. A revoked or expired key gets 401 no_autenticado.

Permission Allows
dte:read Read documents, events, their JSON, and their PDF
dte:emit Validate and issue documents, returns, and event 17
dte:invalidate Invalidate documents and transmit contingencies
clientes:read Read customers
clientes:write Create, edit, and delete customers
productos:read Read products
productos:write Create, edit, and delete products
emisor:read View the issuer and its establishments
emisor:write Edit the issuer, establishments, and credentials
claves:manage Create and revoke API keys
webhooks:manage Configure webhooks and view their deliveries
auditoria:read View the audit log
registros:read View the logs of requests made with API keys

An API key can never carry emisor:write, claves:manage, or auditoria:read: those are done in the dashboard.

Dashboard roles: Owner and Administrator have every permission; Biller (member) has dte:read, dte:emit, clientes:*, productos:*, and emisor:read.

If a permission is missing, the response is 403 sin_permiso with the missing permission in details.permiso.

  • Read only: dte:read, clientes:read, productos:read, emisor:read.
  • Invoicing: the above plus dte:emit, clientes:write, productos:write.
  • Invalidating: add dte:invalidate only if you really need it.

The dashboard uses Better Auth at /api/auth/* (sign-up, sign-in, organizations, and invitations). A user with no organization gets 409 sin_organizacion; a user who belongs to several and has none active gets 409 sin_organizacion_activa with the list in details.organizaciones.

Cookie-authenticated requests that modify data must come from the dashboard’s own origin; otherwise, 403 origen_no_permitido.

If the installation sends account emails, the «Confirma tu correo» link opens /auth/confirmar in the dashboard and asks for the password the account was created with. Whoever doesn’t know it sets a new one: the old one stops working, every session is closed, the email is confirmed and a session opens. Underneath it’s POST /api/auth/confirmar-correo with { token, password } or { token, newPassword }. The link alone (GET /api/auth/verify-email) no longer confirms or signs anyone in. Resetting the password of an unconfirmed account also confirms it.

With Cloudflare Turnstile enabled, sign-up, sign-in and the password-reset request ask you to solve the widget; the token goes in the x-turnstile-token header. See Self-hosting.

Each person owns up to 10 organizations (the ones they’re invited to don’t count). Person and organization names allow 120 characters, the slug 60, metadata 4 KB, and the image and logo must be an https:// URL of up to 2 KB.

The MH API password and the certificate’s private key are stored encrypted with AES-256-GCM and are never returned: GET /emisor only reports whether they are loaded. They are not recorded in the audit log or in any other log.

For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.