Embedded JavaScript SDK

Loading the SDK

The Inkfree Embedded JavaScript SDK (inkfree-embed.js) is a standalone, zero-dependency library that mounts widgets in an iframe, automatically resizes containers, handles secure cross-window postMessage communications, and applies brand styling.

<!-- Load the SDK from the Inkfree host -->
<script src="https://sign.inkfree.app/embed/inkfree-embed.js"></script>

Mounting widgets

Use InkfreeEmbed.mount(options) to initialize either the sender widget or the signing widget:

var widget = InkfreeEmbed.mount({
  container: "#widget-container",       // DOM element or CSS selector string
  type: "sign",                        // "sign" for signing or "create" for sender widget
  token: sessionToken,                 // 300s one-time token minted by your server
  theme: {                             // Optional brand styling
    primaryColor: "#0a5aff",
    buttonTextColor: "#ffffff"
  },
  minHeight: "540px",                  // Initial frame minimum height
  title: "Document Signing"            // Accessible iframe title
});

// Subscribe to real-time events:
widget.on("sign_completed", function (event) {
  console.log("Sign completed for envelope:", event.requestId);
});

// Remove iframe and cleanup listeners when navigating away:
// widget.destroy();

mount() options reference

What mount() returns and throws

• mount() returns the widget object. It has on(event, callback), off(event, callback) (both return the widget, so calls can be chained), destroy() and the iframe element.
• It throws an Error synchronously if type is not "sign" or "create", if token is missing, if the container is not found, or if the script was not loaded from the Inkfree app host.
• A token problem (used, expired, invalid) does not throw. It appears inside the widget as an error screen. See the errors reference below.

Iframe sandboxing & lifecycle

• Automatic sandboxing: The SDK mounts the iframe with sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads", an empty allow list, and referrerpolicy="strict-origin", so only your page's origin (never its path) is sent as the referrer.
• Always use the SDK (not hand-written iframes): The SDK manages origin verification, cryptographic fragment passing, cross-window messaging, dynamic auto-resizing, and brand styling. Hand-written iframe URLs are internal and subject to change.
• Resizing & ceilings: The SDK automatically resizes the iframe to fit document content. The sender widget sizes itself to frame height; set a sensible minHeight (recommended "820px") and, if you want a ceiling, constrain the iframe with CSS (e.g. iframe { max-height: 900px; }).
• Instance isolation: Multiple widgets can coexist on a single parent page. The SDK filters postMessage events by origin and window reference so each instance only receives its own events.
• Cleanup with destroy(): Calling widget.destroy() removes the iframe from the DOM and detaches message event listeners. Always call this before re-mounting a new widget in the same container.

Custom themes and branding

Pass a theme object to mount() to match your company's UI:

theme: {
  primaryColor: "#0a7d5c",     // Hex color for buttons, active steppers, and focus states
  buttonTextColor: "#ffffff"   // Text color for filled primary buttons
}

What works now

• The colors apply across the widget: action buttons (including Next, Back, Send, Finish, Adopt & sign, Complete Signing), hover and active states, focus rings, selected options, and signer-side accents.
• buttonTextColor specifies the foreground text color on filled buttons. Choose a text color with sufficient contrast against your primaryColor.

Order of precedence

1. Widget theme: Colors passed to mount({ theme }).
2. Account branding: Colors configured in your Inkfree dashboard under Settings > Branding.
3. Inkfree default: Fallback default color palette.

Limits

• Only two colors are supported (primaryColor and buttonTextColor). Logos, custom fonts, injected CSS, border radius adjustments, and dark mode are not supported. Parent pages cannot style the inner DOM of the iframe.
• Certain parts of the sender widget keep the default Inkfree colors (such as portions of the step indicator bar and step layouts). Validate your color combinations on both sender and signer screens prior to launch.
• Because colors reach the iframe shortly after initialization, a brief flash of default colors is possible on first paint.

Events reference

Subscribe to events using widget.on(event, callback) and unsubscribe with widget.off(event, callback):

Your callback receives one object: { type, requestId, ts, data }. type is the event name, requestId is the draft or envelope id, ts is the time in milliseconds, and data is the payload from the table above. An error event carries data.code and data.recoverable.

Errors reference

Widget errors (the 'error' event)

If the session ends while a user is working, the widget shows "Your session has ended.", sends an error event with SESSION_EXPIRED, and your page should mint a new token. The widget never redirects the user to an Inkfree login page. The text inside the widget is fixed for each code; the detailed server message is for your server logs only.

API errors (your server's calls)

Most errors from the mint and draft calls use the standard error body described in Errors: { "message": "CODE: explanation", "code": 400, "correlationId": "..." }. The message starts with the code name. Quote the correlationId when you contact support. A missing or invalid API key (HTTP 401) is rejected before the request reaches the embed code, so that body has the form { "timestamp", "status": 401, "error", "message": "invalid api key", "path" }. Always branch on the HTTP status and the code at the start of message.

When the widget redeems a token inside the iframe, a failure comes back as HTTP 401 with TOKEN_INVALID, TOKEN_EXPIRED or TOKEN_USED. You do not make that call yourself; the widget does, and shows the matching message. Mint a new token to retry.

Testing your integration

1. Test environment setup

1. Create a test API key in your Inkfree dashboard and register your local origin (e.g. http://localhost:5173).
2. Implement the backend token minting route and frontend mounting script.
3. Revoke test keys upon completing security testing.

2. Comprehensive verification checklist

Feature availability

Available features

• API-key authentication, origin whitelisting, one-time 300s tokens, and 60-minute sessions.
• Embedded signing: signing order sequence, field navigator, adopt or draw signature, decline, and postMessage events.
• Embedded approvers: approvers approve or reject inside your app in the signing widget, with approval order and approver groups. Inkfree emails them nothing.
• Embedded sender widget: the same four steps as Inkfree's own wizard: upload documents, signers and CC recipients with a signing order and signing delays, approvers and approver groups (who approve inside your app), drag-and-drop field placement with the account's custom fields and AI auto-place, the AI assistant and AI insights, email subject and message, expiry, signer permissions (download, completion notification, attach signed copies), scheduled send, and a branded email preview. Delegation and reminder emails are not offered, because they would take a signer out of your app. Each option needs the matching feature on the account's plan.
• Security for every signer, including those who sign in your app: an access code, a one-time code by email or by text, and identity verification where it is set up. The signer is asked for it inside the iframe.
• Optional document uploads and signer pre-population on draft creation; pre-placed field templates; idempotent requests.
• Signers added in the sender widget sign in your app (EMBEDDED); partner-specified signers retain their mode.
• JavaScript client SDK with event subscriptions, container auto-resizing, and two-color theme support with account branding fallback.
• Server webhooks and envelope REST API for verification and signed PDF retrieval.

Not available

Known considerations

• Signer page colors: Verify your color contrast across every step of the signing workflow before deploying to production.
• Responsive layout: Both widgets switch to a phone layout when the iframe is narrow, and switch back when it is widened. The sender widget needs a frame at least 320px wide; below that it shows the VIEWPORT_TOO_SMALL message.

Complete code samples

Frontend HTML + JavaScript

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>In-App Signing</title>
  <script src="https://sign.inkfree.app/embed/inkfree-embed.js"></script>
</head>
<body>
  <div id="signing-box" style="width: 100%; height: 800px;"></div>

  <script>
    // 1. Fetch one-time token from your server
    fetch("/api/get-signing-token?envelopeId=12345")
      .then(res => res.json())
      .then(data => {
        // 2. Mount the Inkfree signing widget
        var widget = InkfreeEmbed.mount({
          container: "#signing-box",
          type: "sign",
          token: data.token,
          theme: {
            primaryColor: "#0a7d5c",
            buttonTextColor: "#ffffff"
          }
        });

        // 3. Handle events
        widget.on("sign_completed", function (event) {
          alert("Thank you for signing!");
          window.location.href = "/dashboard";
        });

        widget.on("error", function (err) {
          console.error("Widget error:", err.data.code);
        });
      });
  </script>
</body>
</html>

Backend server: Mint signing token

curl -X POST "https://services.softsages.com/core/api/v1/inkfree/embed/sessions" \
  -H "X-API-Key: sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "signing",
    "requestId": "envelope-id-here",
    "signerEmail": "signer@example.com",
    "parentOrigin": "https://app.example.com"
  }'

Backend server: Create empty draft for sender widget

curl -X POST "https://services.softsages.com/core/api/v1/inkfree/embed/drafts" \
  -H "X-API-Key: sk_live_YOUR_API_KEY" \
  -F 'request={"emailSubject":"Vendor NDA","emailMessage":"Please sign the agreement.","expirationDays":30,"signers":[]}'