Embedded signing

L'embedded signing permet à tes utilisateurs de signer sans quitter ton interface. Inkr expose la page de signature dans une iframe sécurisée par un JWT à durée de vie courte (TTL 24h par défaut, configurable jusqu'à 24h max).

URL embed

À la création d'une submission, chaque submitter reçoit un champ embed_src dans la réponse :

{
  "submitters": [
    {
      "id": "sbm_01J5HZ...",
      "email": "alice@example.com",
      "signing_url": "https://sign.getinkr.eu/s/abc123",
      "embed_src": "https://sign.getinkr.eu/s/abc123?embed_token=eyJhbGc..."
    }
  ]
}

• signing_url : URL publique standard, à utiliser si tu veux que ton signataire accède via email ou lien direct.
• embed_src : URL avec JWT valable 24h, sécurisée pour iframe.

Intégrer en iframe

<iframe
  src="https://sign.getinkr.eu/s/abc123?embed_token=eyJhbGc..."
  width="100%"
  height="800"
  style="border: none; max-width: 1200px;"
  allow="clipboard-write"
></iframe>

L'iframe Inkr écoute les événements postMessage pour communiquer avec la fenêtre parente :

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://sign.getinkr.eu') return

  switch (event.data.type) {
    case 'inkr:signed':
      console.log('Submitter signed:', event.data.submitter_id)
      // Affiche un toast côté ton UI, navigate vers la suite, etc.
      break
    case 'inkr:declined':
      console.log('Submitter declined')
      break
  }
})

Régénérer un embed_token

Si le token a expiré (TTL dépassé) :

curl -X POST https://api.getinkr.eu/v1/submitters/sbm_01J5HZ.../embed_token \
  -H "Authorization: Bearer $INKR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "ttl_seconds": 3600 }'

La réponse retourne un nouveau embed_src valable la durée spécifiée (clamp [60, 86400]).

Sécurité

• Le JWT contient uniquement l'ID submitter et l'expiration. Aucune info personnelle dans le token.
• Le JWT est signé HMAC-SHA256 avec un secret applicatif (rotation possible côté Inkr sans invalider les sessions actives via grace period).
• L'iframe ajoute les headers Content-Security-Policy et X-Frame-Options pour empêcher le clickjacking.
• Inkr n'autorise PAS les iframes cross-origin malicieuses : seul le domaine d'origine du token (le owner de l'API key) peut embed.

Limitations

• L'embed_src ne fonctionne pas pour les browsers qui bloquent les cookies tiers (Safari ITP strict, etc.) si Inkr a besoin d'écrire un cookie de session. Workaround : ouvrir l'URL en popup standard (window.open(signing_url)) plutôt qu'iframe.
• Sur mobile, la signature dessin marche bien mais l'expérience est plus agréable en fullscreen. Considère ouvrir en popup sur mobile, en iframe sur desktop.