Autenticación

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

Envío de la clave

Utilice cualquiera de estas dos cabeceras:

# 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 la forma bf_live_… o bf_test_…. Si falta la clave, se devuelve 401 (unauthorized); una clave mal formada, revocada o caducada también devuelve 401. Guarde las claves en su servidor: no las incluya nunca 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	Solo se entrega a los miembros de su organización	Se entrega a todos los destinatarios
Facturación	Gratuita e ilimitada; nunca se contabiliza	Los sobres completados se descuentan de 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 petición: ?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 los endpoints de webhook del mismo modo. Todos los sobres y todas las cargas de webhook indican en qué modo están (testMode).

Creación y revocación de claves

Las claves se gestionan en el panel, en Configuración › Claves de API, y pueden hacerlo los miembros con el permiso apikey:manage (propietarios y administradores). El secreto se muestra una sola vez, al crear la clave. A cada clave se le puede asignar un nombre, un modo, una caducidad (de 1 a 365 días, o ninguna) y unos ámbitos.

Ámbitos

Los ámbitos de una clave son los permisos de la organización que puede utilizar. Por defecto, una clave nueva recibe los permisos de quien la crea, salvo los de administración (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), y nadie puede conceder a una clave un permiso que no tenga. Una llamada fuera de los ámbitos de la clave devuelve 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 la clave
`template:read`	Listar y leer plantillas, versiones y sus PDF
`template:write`	Crear plantillas, subir archivos, guardar borradores y eliminar plantillas que no se usan
`template:publish`	Publicar un borrador como versión nueva
`envelope:read`	Listar y leer sobres, documentos y registros de auditoría; listar enlaces de firma
`envelope:send`	Crear sobres, sesiones de firma y enlaces de firma; reenviar enlaces
`envelope:void`	Anular sobres en curso
`org:manage`	Gestionar endpoints de webhook y volver a entregar eventos; leer la configuración de la organización
`billing:manage`	Consultar el uso (`GET /v1/usage`) y los importes de las facturas

Para gestionar endpoints de webhook hace falta org:manage, que las claves no reciben por defecto: registre los endpoints en el panel o cree expresamente una clave con ese ámbito.

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, subida 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 utilizan la página alojada y <bf-signing> con un token de sesión (bfs_…) o con el token de acceso por el que se canjea (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.

Al crear una cuenta con contraseña se envía un correo: 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 cuenta no cambia nada y obtiene exactamente la misma respuesta que un registro nuevo; el titular de la dirección recibe un correo en el que se le explica cómo iniciar sesión.
Las contraseñas tienen entre 12 y 128 caracteres y se guardan como hashes scrypt con sal. Se rechaza cualquier contraseña nueva que aparezca en una filtración de datos conocida: solo se envían los cinco primeros 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 comprobarla.
¿Ha olvidado su contraseña? El correo de restablecimiento lleva a una página en la que puede elegir una nueva. El enlace funciona una sola vez y caduca al cabo de una hora, y al usarlo se cierra la sesión en todos los dispositivos.
¿Aún no tiene contraseña? Las cuentas creadas con un código, un enlace, una llave de acceso o Google / Microsoft siguen iniciando sesión del mismo modo y pueden añadir una contraseña en Configuración › Cuenta. Para establecer la primera contraseña es necesario 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, hace falta la actual. En ambos casos se cierran sus demás sesiones.
Los errores nunca revelan si existe una cuenta: una contraseña incorrecta, una dirección desconocida y una cuenta sin contraseña reciben 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; una vez superado el límite, la respuesta es 429 hasta que transcurra el intervalo.
SSO de la empresa: cuando su organización impone el SSO, los miembros con direcciones de sus dominios inician sesión únicamente 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 petición

Todas las respuestas incluyen una cabecera x-request-id, y todos los cuerpos 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; si no, la API genera uno. Indíquelo cuando se ponga en contacto con el servicio de asistencia.