Embed

El flujo normal mantiene separadas las credenciales del integrador y el token temporal del runtime:

Backend integrador → POST /v1/embed/sessions
Frontend → <consensa-consent>
Runtime Consensa → bootstrap, identidad y decisión
Frontend → eventos públicos sanitizados

Antes de crear la sesión: metadata del Flow

GET /v1/embed/flows/{configKey} (scope consent:runtime) devuelve la versión publicada vigente del Flow: consentimientos, política de autenticación congelada, identifiers requeridos y, si el Flow contiene REDEC, las finalidades y objetivos admitidos por el Regulatory Profile. Envía el header Origin de la página host; origin.allowed es informativo y POST /v1/embed/sessions sigue siendo el punto de enforcement. No crea sesión, interacción ni consentimiento.

1. Crear la sesión

Ejecuta esta llamada desde tu backend. origin debe coincidir exactamente con un origen permitido para el tenant.

La operación requiere consent:runtime. El ejemplo afirma que el banco ya autenticó al cliente con authentication.source: "client", por lo que la API key necesita además consent:identity-assert. Con source: "consensa", ese scope adicional no es requisito de creación y el runtime gestiona la verificación.

curl --request POST "$CONSENSA_API_URL/v1/embed/sessions" \
  --header "Authorization: Bearer $CONSENSA_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: embed-customer-4821-01" \
  --data '{
    "configKey": "general-consent",
    "userReference": "customer-4821",
    "origin": "https://bank.example",
    "authentication": {
      "source": "client",
      "method": "bank_session",
      "authenticatedAt": 1787702400000,
      "reference": "session-reference-8f2a"
    }
  }'

La respuesta es un pre-check. Si presentation.required es false, no hace falta una nueva interacción de consentimiento según el estado evaluado en ese instante: continúa el flujo y no montes el componente. En ese caso Consensa no crea sesión ni InteractionTokens.

Este resultado no autoriza la operación. Puede existir TOCTOU entre el pre-check y el tratamiento: el consentimiento puede revocarse, expirar o cambiar. Para General ejecuta /v1/authorization/check, cuando corresponda, inmediatamente antes de la operación. Para REDEC conserva el gate regulatorio especializado inmediatamente antes del acceso CMF. Una revocación o expiración posterior al pre-check siempre debe respetarse.

Si presentation.required es true, la respuesta incluye sessionId, interactionId, launchTicket, launchExpiresAt y expiresAt. launchTicket no es una credencial de sesión: es un ticket de un solo uso que vence a los 60 segundos. Pídelo justo antes de montar el componente, no lo registres, no lo persistas y nunca lo pongas en un atributo HTML ni en una URL.

2. Montar el componente

Ejecuta esta sección sólo cuando presentation.required === true.

Carga el bundle host, crea el elemento con la URL de runtime del ambiente y el sessionId (no es secreto), y entrega el ticket con launch(). El componente monta un iframe Consensa cross-origin y le pasa el ticket por postMessage sólo después de que el runtime se anuncia. El runtime lo canjea una única vez, ligado al origen de tu página que certifica el navegador, por la credencial real de la sesión. Esa credencial vive sólo dentro del iframe: ni tu código, ni scripts de terceros ni herramientas de session replay pueden leerla.

<script type="module" src="https://embed.consensa.example/host.js"></script>
<div id="consent-slot"></div>

<script type="module">
  const consent = document.createElement('consensa-consent');
  consent.setAttribute('title', 'Consentimiento para solicitud de crédito');
  consent.setAttribute('src', 'https://embed.consensa.example/runtime.html');
  consent.setAttribute('session', sessionId);
  document.querySelector('#consent-slot').replaceChildren(consent);
  consent.launch(launchTicket);
</script>

El runtime sólo acepta ser enmarcado por el origen exacto con el que creaste la sesión (Content-Security-Policy: frame-ancestors), también cuando tu página está a su vez dentro de otro frame. Si tu página no corre en ese origen, el canje falla con ORIGIN_NOT_ALLOWED y el componente muestra el estado inválido. Si el ticket venció (consensa:expired), crea una nueva sesión desde tu backend. runtime.html es un recurso técnico provisto por Consensa: el runtime siempre llama a la API por su propio origen y no admite otro destino. Los endpoints usados por el iframe son administrados por Consensa y no forman parte de la Integration API.

3. Escuchar el resultado

Una interacción con un solo consentimiento emite consensa:granted o consensa:denied.

consent.addEventListener('consensa:granted', ({ detail }) => {
  console.log(detail.interactionReference, detail.outcome);
});

consent.addEventListener('consensa:denied', ({ detail }) => {
  console.log(detail.interactionReference, detail.outcome);
});

Los eventos son notificaciones sanitizadas para UX. Confirma siempre el resultado de negocio desde tu backend mediante la API de Consent.

Seguridad del canal

El host valida el origen exacto del runtime, el source exacto del iframe y la versión del protocolo. Consensa nunca usa postMessage("*") y no expone tokens, identificadores internos ni datos personales en eventos públicos.