Autenticación de máquinas

Sus integraciones se autentican ante bb-sign con una credencial de API y operan con las mismas garantías de aislamiento que un usuario de la organización. Un administrador crea la credencial en Configuración, pestaña Credenciales de API; los roles de espacio de trabajo que se le asignan determinan lo que puede hacer. Esta página es normativa.

Un único modelo de identidad

Una máquina se autentica con client credentials de OAuth2 contra el realm bbsign. bb-sign procesa su token con el mismo código que procesa el token de una persona, porque Keycloak emite ambos de la misma forma:

• Una cuenta de servicio de Keycloak es un registro de usuario real, no un principal sin usuario.
• El mismo mapeador de atributos que agrega el claim bb_sign_org_id al token de una persona lo agrega al token de máquina, a partir de un atributo del usuario de la cuenta de servicio.
• Todas las decisiones de alcance por organización pasan por un único punto de la API, que lee ese claim con independencia del tipo de concesión (grant type).

En consecuencia, el aislamiento por organización se hereda: un token de máquina queda limitado por la misma comprobación que el de una persona.

Obtener un token

curl -s -X POST https://auth.binarybridges.co/realms/bbsign/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=<your-client-id> \
  -d client_secret=<your-secret>

{ "access_token": "eyJ...", "expires_in": 300, "token_type": "Bearer" }

Envíelo como bearer token en cada solicitud:

curl -H "Authorization: Bearer $TOKEN" https://sign-api.binarybridges.co/api/v1/envelopes

Claims requeridos

Claim	Valor	Función
bb_sign_org_id	El UUID de la organización propietaria	Toda lectura y escritura con alcance de organización se resuelve a partir de este valor. Si falta, la API responde 403 (ver Estados de error)
realm_access.roles	contiene org_api	El rol que admiten los endpoints con alcance de organización
aud	contiene bb-sign	Si falta, el validador de audiencia rechaza el token antes de evaluar la autorización

Sin el mapeador de audiencia, el token falla en la validación; sin el atributo de organización, falla en la autorización. En ambos casos el acceso se niega. Las credenciales creadas desde Configuración incluyen los tres claims.

Vigencia del token

Un token es válido durante 300 s (expires_in). Se valida contra el JWKS del realm sin llamada de introspección, de modo que conserva su validez hasta que expira aunque la credencial se haya revocado. Toda revocación de acceso se hace efectiva dentro de esa ventana.

Alcance de una credencial

En el nivel de organización, una credencial tiene únicamente label:read y workspace:read: puede listar las claves de etiqueta y los espacios de trabajo a los que pertenece. Lo que puede hacer con los sobres depende del rol que tenga en cada espacio de trabajo. Al crear la credencial, el formulario solicita un espacio de trabajo y un rol: «General con Gestor es la opción predeterminada». Un administrador puede agregarla después a otros espacios desde Configuración, pestaña Espacios de trabajo, sección Miembros.

Permisos de espacio por rol de espacio

Permiso	viewer	auditor	contributor	manager
envelope:read	Sí	Sí	Sí	Sí
archive:read	Sí	Sí	Sí	Sí
audit:read	No	Sí	Sí	Sí
document:download	No	Sí	Sí	Sí
envelope:create	No	No	Sí	Sí
envelope:update	No	No	Sí	Sí
document:upload	No	No	Sí	Sí
label:assign	No	No	Sí	Sí
envelope:send	No	No	Sí	Sí
envelope:cancel	No	No	No	Sí

• GET /api/v1/workspaces devuelve General y los espacios de trabajo en los que la credencial tiene un rol. Envíe el id de uno como workspaceId al crear un sobre; si lo omite, el sobre se archiva en General.
• Una credencial puede pertenecer como máximo a 50 espacios de trabajo.
• Un cambio de rol se aplica cuando se emite el siguiente token de la credencial, es decir, en menos de 300 s.
• La organización siempre se toma del token, nunca de la solicitud. Una máquina no envía orgId al crear un sobre; si lo envía, no cambia la organización del sobre.

Permisos reservados a personas

Una credencial nunca recibe estos permisos de organización, aunque un administrador intente concederlos. Son protecciones contra la escalada de privilegios en el catálogo de permisos:

• credential:manage
• webhook:manage
• workspace:manage
• workspace:manage-members
• workspace:access-all

La administración de organizaciones, usuarios, cuotas, certificados, etiquetas, el archivo, la auditoría, credenciales, webhooks y espacios de trabajo se realiza en la interfaz, a cargo de un administrador de la organización. La ceremonia de firma (/api/v1/sign/**) es pública por diseño y está limitada a un firmante por el token de su enlace; las integraciones no la utilizan.

Los dos tipos de rechazo se distinguen de forma intencional:

Solicitud	Respuesta
Una operación para la que la credencial no tiene el permiso de organización	403, sin cuerpo
Un sobre o espacio de trabajo que la credencial no puede ver, o que no existe	404, idéntico a «no existe»

Estados de error

Estado	Significado	Causa habitual	Acción
401	Sin token, token expirado o token que el realm no valida	Falta el encabezado Authorization; token con más de 300 s	Solicite un token nuevo; revise el prefijo Bearer
403 en un endpoint del flujo	Autenticado, pero sin permiso en el nivel de organización	Llamar a una operación de administración que solo existe en la interfaz	Confirme que la operación existe en la referencia de la API
403 en GET /api/v1/envelopes en particular	El token incluye org_api pero no bb_sign_org_id	Una credencial que no se creó desde Configuración	Revóquela y cree una nueva en Configuración, pestaña Credenciales de API
404 en un sobre o espacio de trabajo	La credencial no tiene rol en ese espacio, o el id es incorrecto	Un espacio de trabajo que nunca se asignó a la credencial	Pida a un administrador que agregue la credencial en Miembros, o use General

En el caso de la tercera fila, el acceso se niega: un token sin el claim de organización no recibe datos de ninguna organización.

Vigencia del token y revocación

• Un token es válido durante 300 s y no se valida por introspección.
• Revocar detiene de inmediato la emisión de tokens nuevos. La confirmación indica que las solicitudes con un token ya obtenido pueden seguir funcionando hasta que ese token expire: «revocar no corta el acceso que ya está en curso». La credencial aparece como Revocada — en expiración hasta que expira el último token emitido, luego como Revocada, y permanece en la lista durante 90 días. Ante una filtración, considere la credencial activa hasta que haya transcurrido ese tiempo.
• Rotar reemplaza el secreto sin periodo de gracia: «El secreto actual deja de funcionar de inmediato. Cualquier integración que lo use fallará hasta que la vuelvas a desplegar con el nuevo secreto».
• Una organización puede tener como máximo 10 credenciales activas.

Crear una credencial

Un administrador de la organización crea las credenciales desde la interfaz:

1. Abra Configuración, pestaña Credenciales de API, y seleccione Nueva credencial.
2. Asígnele una etiqueta que identifique el sistema que la usará y, en Acceso, elija el espacio de trabajo y el rol.
3. Copie el ID de cliente y el Secreto de cliente. El secreto se muestra una sola vez: se almacena únicamente en Keycloak y bb-sign no conserva copia.
4. Entregue ambos valores al sistema que los usará a través de su gestor de secretos, nunca por control de versiones ni por chat.

La gestión desde la interfaz se describe en Credenciales de API.