Autenticación

Cada petición lleva una API key de tu organización en la cabecera Authorization. La key solo ve los datos de esa organización y solo lo que permitan sus scopes.

Cómo enviar la key

http

Authorization: Bearer bn_live_<64 caracteres hexadecimales>

Todas las keys empiezan por bn_live_. No hay keys de pruebas: si quieres probar sin tocar datos reales, hazlo con una obra de demostración (ver include_demo en Obras).

Trata la key como una contraseña: guárdala en una variable de entorno o un gestor de secretos, en el servidor. Nunca la pongas en una web o una app móvil, donde cualquiera podría leerla.

Crear una key

Entra como administrador en Configuración → Integraciones.
En API REST y Webhooks, pulsa Nueva API key y ponle un nombre que diga para qué es (p. ej. Contabilidad — Holded).
Marca solo los permisos que necesite esa integración.
Si quieres, ponle caducidad (7, 30, 90 o 365 días, o una fecha). Por defecto no caduca.
Copia la key: solo se enseña una vez. Después solo verás su comienzo (bn_live_xxxx).

Permisos (scopes)

Cada endpoint indica el permiso que necesita. Si a la key le falta, la respuesta es 403:

403

{
  "error": {
    "code": "insufficient_scope",
    "message": "Missing required scope: read:financials"
  }
}

Scope	Da acceso a
`read:projects`	Obras (listado, detalle y agentes) y obras borradas.
`read:budgets`	Presupuestos y ofertas (con sus partidas), agentes del presupuesto y presupuestos borrados.
`read:invoices`	Facturas de compra.
`read:delivery_notes`	Albaranes.
`read:providers`	Proveedores y subcontratas con sus contactos, proveedores de cada obra o presupuesto, cumplimiento CAE y proveedores borrados.
`read:documents`	Documentos de las obras: listado, texto extraído y descarga del archivo.
`read:users`	Usuarios de la organización y quién ve cada obra o presupuesto. Son datos personales (nombre y email).
`read:financials`	Resumen económico: coste, venta, certificado, facturado y margen. Aparte para poder compartir las obras sin compartir los márgenes.
`read:prices`	Bases de precios. Solo la usa el servidor MCP.
`write:webhooks`	Listar, crear, probar y borrar webhooks.

Revocar una key

En la misma pantalla de Integraciones. Deja de funcionar al momento: las peticiones con ella reciben 401 con el código revoked (o expired si caducó).

Cuándo se corta el acceso

401 — falta la cabecera, la key no existe, está revocada o ha caducado.
402 — la organización no está al corriente de pago: prueba terminada (trial_expired), pago de la suscripción sin completar (payment_pending), recibo impagado o suscripción cancelada (payment_required). Es lo mismo que bloquea la app.
403 — a la key le falta el permiso del endpoint.

Todos los códigos, en Errores.

Buenas prácticas

Una key por integración: si tienes que revocar una, las demás siguen funcionando.
Solo los permisos necesarios. read:users y read:financials dan acceso a datos personales y a tus márgenes: concédelos solo si hacen falta.
Revoca la key en cuanto sospeches que se ha filtrado y crea otra.