Autenticación

La API autentica a los servidores con claves de API de la organización. Una clave pertenece a una organización (no a una persona), tiene un conjunto de permisos y funciona en un único modo: prueba o producción.

Envío de la clave

Use cualquiera de estos encabezados:

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

Las claves tienen el formato bf_live_… o bf_test_…. Si falta la clave, la respuesta es 401 (unauthorized); una clave con formato incorrecto, revocada o vencida también da 401. Mantenga las claves en su servidor: nunca las incluya en un navegador ni en una aplicación móvil. Para firmar en el navegador, genere en su lugar una sesión de firma.

Claves de prueba y de producción

	Prueba (`bf_test_…`)	Producción (`bf_live_…`)
Documentos	Se generan con una marca de agua `TEST`	Sin marca de agua
Correo electrónico	Se entrega solo a los miembros de su organización	Se entrega a todos los destinatarios
Facturación	Gratuita e ilimitada, nunca se contabiliza	Los sobres completados cuentan para su plan
Datos	Los sobres, enlaces y endpoints de webhook creados con la clave están en modo de prueba	En modo de producción

El modo lo determina la clave, nunca la solicitud: ?test_mode=true en POST /v1/envelopes solo se aplica a las sesiones del panel. Las listas (GET /v1/envelopes, GET /v1/signing-links) solo devuelven elementos del modo de la clave, y los eventos de un sobre solo se envían a endpoints de webhook del mismo modo. Cada sobre y cada carga útil de webhook indica en qué modo está (testMode).

Creación y revocación de claves

Las claves se administran en el panel, en Configuración › Claves de API, por los miembros que tienen el permiso apikey:manage (propietarios y administradores). El secreto se muestra una sola vez, al crear la clave. Puede asignarle a una clave un nombre, un modo, un vencimiento (de 1 a 365 días, o ninguno) y alcances.

Alcances

Los alcances de una clave son los permisos de la organización que puede usar. De forma predeterminada, una clave nueva recibe los permisos de quien la crea, salvo los administrativos (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), y nadie puede otorgar a una clave un permiso que no tiene. Una llamada fuera de los alcances de la clave da 403 e indica el permiso que falta:

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Permiso	Permite a una clave
`template:read`	Enumerar y leer plantillas, versiones y sus PDF
`template:write`	Crear plantillas, subir archivos, guardar borradores y eliminar plantillas sin usar
`template:publish`	Publicar un borrador como una nueva versión
`envelope:read`	Enumerar y leer sobres, documentos y registros de auditoría; enumerar enlaces de firma
`envelope:send`	Crear sobres, sesiones de firma y enlaces de firma; reenviar enlaces
`envelope:void`	Anular sobres en curso
`org:manage`	Administrar endpoints de webhook y volver a entregar eventos; leer la configuración de la organización
`billing:manage`	Leer el uso (`GET /v1/usage`) y los importes de las facturas

Para administrar endpoints de webhook se necesita org:manage, que las claves no reciben de forma predeterminada: registre los endpoints en el panel o cree explícitamente una clave con ese alcance.

Qué acepta cada endpoint

Cada operación de la referencia de la API indica sus esquemas de seguridad. En resumen:

Clave de API o sesión del panel: plantillas, sobres, sesiones de firma, enlaces de firma, endpoints de webhook, configuración de la organización, resumen de facturación y uso.
Solo sesión del panel: claves de API, tokens de SCIM, configuración de la conexión SSO, carga del logotipo de la organización, pago y portal de facturación, y visualización de un secreto de webhook.
Token de firmante: /v1/signing/*, que usan la página alojada y <bf-signing> con un token de sesión (bfs_…) o el token de acceso por el que se intercambia (bfa_…).
Público: /v1/links/{id} (enlaces permanentes), /v1/sso/discover y la API de verificación (/v1/public/*, /.well-known/bona-fide/keys.json).

Inicio de sesión en el panel

Las personas (no los servidores) inician sesión en el panel en https://app.bonafidesign.com/sign-in. La opción predeterminada es correo electrónico y contraseña; las alternativas son un código de seis dígitos enviado por correo (Enviarme un código por correo), un enlace mágico, una llave de acceso, Google o Microsoft, y el SSO de su empresa.

Crear una cuenta con contraseña envía un correo electrónico: un código que confirma que la dirección es suya. Hasta entonces, la contraseña no permite iniciar sesión. Registrarse con una dirección que ya tiene una cuenta no cambia nada y obtiene exactamente la misma respuesta que un registro nuevo; el titular de la dirección recibe un correo que le explica cómo iniciar sesión.
Las contraseñas tienen entre 12 y 128 caracteres y se almacenan como hashes scrypt con sal. Se rechaza una contraseña nueva que aparezca en una filtración de datos conocida: solo se envían los primeros cinco caracteres de su hash SHA-1 a Have I Been Pwned (k-anonimato), nunca la contraseña. Si ese servicio no responde en dos segundos, la contraseña se acepta sin la comprobación.
¿Olvidó su contraseña? El correo de restablecimiento enlaza a una página donde puede elegir una nueva. El enlace funciona una sola vez y vence después de una hora, y al usarlo se cierra su sesión en todos los dispositivos.
¿Todavía no tiene contraseña? Las cuentas creadas con un código, un enlace, una llave de acceso o Google / Microsoft siguen iniciando sesión de esa manera y pueden agregar una contraseña en Configuración › Cuenta. Para establecer la primera contraseña se necesita haber iniciado sesión en los últimos 15 minutos (la página le envía un código por correo para confirmar que es usted); para cambiarla se necesita la actual. En ambos casos se cierran sus otras sesiones.
Los errores nunca revelan cuentas: una contraseña incorrecta, una dirección desconocida y una cuenta sin contraseña obtienen la misma respuesta, y una solicitud de restablecimiento siempre indica que el correo está en camino.
Límites de frecuencia: el inicio de sesión con contraseña, el registro y las solicitudes de restablecimiento están limitados por dirección IP y por dirección de correo electrónico; al superar el límite, la respuesta es 429 hasta que pase el período.
SSO de la empresa: cuando su organización exige el SSO, los miembros con sus dominios de correo inician sesión solo a través del proveedor de identidad. Para ellos se rechazan las contraseñas, los códigos y los enlaces mágicos; los propietarios conservan el código por correo como acceso de emergencia.

ID de solicitud

Cada respuesta incluye un encabezado x-request-id, y cada cuerpo de error, un requestId. Puede enviar su propio x-request-id (de 8 a 128 caracteres de A-Z a-z 0-9 . _ -) para correlacionar registros; de lo contrario, la API genera uno. Indíquelo cuando se comunique con soporte.