Authentication and keys
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).
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.
Create a key
Section titled “Create 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.
Permissions
Section titled “Permissions”| 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.
Suggested permissions
Section titled “Suggested permissions”- Read only:
dte:read,clientes:read,productos:read,emisor:read. - Invoicing: the above plus
dte:emit,clientes:write,productos:write. - Invalidating: add
dte:invalidateonly if you really need it.
Dashboard session
Section titled “Dashboard session”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.
Email confirmation
Section titled “Email confirmation”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.
Human verification (optional)
Section titled “Human verification (optional)”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.
Account data limits
Section titled “Account data limits”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.
MH credentials
Section titled “MH credentials”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.