API v2 · SDK 3

SDKs

Two SDKs: one in your web page, one on your server. The browser SDK opens the session and sends what it needs by itself; you only call prepareAction. The server SDK asks HEIP for the decision.

Browser SDK

Load it with a script tag, or install it from npm. Both use your public site key.

Script tag. Starts automatically.

<script
  src="https://<sdk-host>/sdk.js"
  data-site-key="pk_live_…"
  async
></script>

Attribute	What it does
`data-site-key`	Your public site key (pk_live_…). Required.
`data-api-url`	The HEIP API origin, if you were given one. Defaults to the hosted API.
`data-auto-start`	Set to `"false"` to start later with `HEIP.init()`.
`data-timeout-ms`	Per-request timeout in milliseconds. Default 9000.

npm. From your bundle.

import { init, prepareAction, destroy } from "heip-sdk";

await init({ siteKey: "pk_live_…" }); // safe to call more than once

const { sessionId, actionNonce } = await prepareAction("checkout");

// later, if the page is torn down
destroy();

Function	What it does
`init(config)`	Starts the SDK and opens a session. Safe to call twice. Options: `siteKey`, `apiBase`, `timeoutMs`.
`prepareAction(action)`	Returns `{ sessionId, actionNonce }` for one protected action. Call it at submit time: the token works once and expires in seconds.
`destroy()`	Stops the SDK and removes its listeners. A later init() starts a fresh session.

Single-page apps: one session per page load. Call prepareAction once per protected action.
Performance: small, passive listeners only, no layout work, compact batches sent in the background. Nothing runs after destroy().
Keys: the SDK refuses a secret key (sk_…) passed as a site key, so a mistake fails loudly instead of leaking.

What it collects

Interaction timing and coarse page state, never content.

It never collects typed characters or which keys were pressed, form values, page content, cookies, storage, identifiers or location. HEIP sees the connecting network address only for rate limiting.

Content Security Policy

If you use a Content Security Policy, allow the SDK host in script-src and the API host in connect-src.

CSP. Hosts are shared with your keys.

Content-Security-Policy:
  script-src 'self' https://<sdk-host>;
  connect-src 'self' https://<api-host>;

Server SDK (Node.js)

Node.js 18 or later, ESM and CommonJS.

Node.js. Runs on your server.

import { HeipServer, allow } from "heip-sdk/server";

const heip = new HeipServer({
  secretKey: process.env.HEIP_SECRET_KEY, // sk_live_…, server only
  // apiBase: "https://<api-host>",       // defaults to the hosted API
  // timeoutMs: 5000,
  // onError: "deny",                     // "allow" only for low-risk actions
});

try {
  const result = await heip.verify({
    sessionId,
    actionNonce,
    action: "checkout",
    context: { orderId: "A-1029" }, // optional, your own ids
  });
  if (!allow(result)) return res.status(403).end();
} catch (err) {
  // HEIP could not be reached or the call failed: fail closed
  return res.status(503).end();
}

Option	Default	What it does
`secretKey`	Required	Your secret key, read from the environment.
`apiBase`	Hosted API	The HEIP API origin.
`timeoutMs`	`5000`	How long to wait for HEIP before failing.
`onError`	`"deny"`	What a network error or timeout means. `"deny"` throws (fail closed); `"allow"` lets the action through.

verify({ sessionId, actionNonce, action, policyId?, context? }) returns the decision. allow(result) is true only for ALLOW. See the Server API for the full response and errors.

Coming

WebView guidance, once tested.
Native iOS and Android SDKs.
Server SDKs for other languages. Until then, use the HTTPS API from any language.

Was this page clear? Tell us what was missing.