Autenticación

La API usa API keys con esquema Bearer. Cada key pertenece a una organización y hereda sus permisos según los scopes que le asignes.

Cómo enviar la key

Incluye la cabecera Authorization en todas las peticiones:

http

Authorization: Bearer bn_live_xxxxxxxxxxxxxxxxxxxx

Nunca expongas una key en el frontend. Las keys con prefijo bn_live_ tienen acceso de escritura — guárdalas en variables de entorno y rótalas si filtras una.

Tipos de key

Prefijo	Entorno	Usar para
`bn_test_`	Sandbox	Pruebas, CI, ejemplos. No mueve dinero real.
`bn_live_`	Producción	Datos reales. Tratar como contraseña.

Generar tu primera key

Entra en settings/integraciones/api.
Pulsa Crear API key.
Asigna un nombre descriptivo (ej. Integración Holded — producción).
Elige los scopes mínimos necesarios.
Copia la key — sólo se muestra una vez. Después sólo verás los últimos 4 caracteres.

Scopes disponibles

Limita lo que puede hacer cada key. Una key con menos scopes es más segura si se filtra.

Scope	Permite
`read:projects`	Listar y leer proyectos.
`write:projects`	Crear, editar y archivar proyectos.
`read:invoices`	Listar y leer facturas.
`write:invoices`	Crear, actualizar y eliminar facturas.
`read:delivery-notes`	Listar y leer albaranes.
`write:delivery-notes`	Crear y conciliar albaranes.
`read:budgets`	Listar y leer presupuestos.
`write:budgets`	Crear y actualizar presupuestos.
`read:providers`	Listar y leer proveedores.
`write:providers`	Crear y editar proveedores.
`manage:webhooks`	Registrar y eliminar endpoints de webhook.

Revocar una key

Desde el panel puedes revocar al instante. Vía API:

curl -X DELETE https://api.buildnexion.com/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer bn_live_xxxxxxxxxxxxxxxxxxxx"

Las llamadas con una key revocada devuelven 401 Unauthorized y el código de error api_key_revoked.

Buenas prácticas

Una key por integración, nunca una key compartida entre sistemas.
Rotación anual mínima, o inmediata si sospechas filtración.
Scopes mínimos: si sólo necesitas leer, no des write:*.
Guarda la key en gestor de secretos (Vercel env vars, AWS Secrets Manager, etc.).