SDK integration

The sandbox HTTP API is a strict subset of the production API shape. The auditor SDK (@enfinitos/sdk-auditor) is published today and integrates with the sandbox by pointing its base URL at https://sandbox.api.enfinitos.com. Other SDKs (sdk-operator-web, sdk-brand) ship at the April 2027 production launch — code snippets below show the expected integration shape for planning purposes. This page is the integration map: which SDK surface maps to which sandbox endpoint, with copy-pasteable code snippets.

@enfinitos/sdk-auditor

Verify any sandbox-issued pack offline. The sandbox publishes the same runtime-keys directory shape as production, with the sandbox-only key. This SDK is published today.

import { verifyAll } from "@enfinitos/sdk-auditor";

const packResponse = await fetch(
  "https://sandbox.api.enfinitos.com/api/sandbox/proof-packs/PAK_ID",
  { credentials: "include" },
);
const { data } = await packResponse.json();

const report = await verifyAll(
  {
    pack: data.pack,
    metering: data.pack.metering,
    settlement: data.pack.settlement,
    verificationKeys: [data.verificationKey],
  },
  { verificationKeySource: "local" },
);

console.log(report.status); // "VALID"

The auditor SDK is fully browser-compatible as of v0.0.2 — the previous version required node:crypto; the current version uses @noble/ed25519 + @noble/hashes + Web APIs only, so this exact snippet runs in a browser tab, a Cloudflare Worker, Node, Deno, or Bun.

Use auditor SDK v0.0.4 or later. The platform seals settlement.v2 packs (3-field content-hash settlement idemKey); earlier published SDK versions reconstruct the legacy 2-field key and report SETTLEMENT_IDEM_KEY_MISMATCH on every line. v0.0.4 is version-aware: it verifies both settlement.v2 and historical settlement.v1 packs.

@enfinitos/sdk-brand

@enfinitos/sdk-brand ships at the April 2027 production launch. The integration shape below is for planning purposes.

The Brand SDK is read-only — it queries delivery proof, metering, and settlement records scoped to a brand’s campaigns. The sandbox runs the brand from the operator side (we sign offers from one sandbox org to another), so the brand surface is presented through the same /api/sandbox/proof-packs and /api/sandbox/inspect endpoints.

import { BrandClient } from "@enfinitos/sdk-brand";

const client = new BrandClient({
  apiKey: "sandbox-cookie-equivalent",
  baseUrl: "https://sandbox.api.enfinitos.com/api/sandbox",
  // The sandbox auths via cookie; the SDK supports cookie-mode
  // when constructed with `auth: { mode: "cookie" }`.
  auth: { mode: "cookie" },
});

const packs = await client.proof.list();

@enfinitos/sdk-operator-web

@enfinitos/sdk-operator-web ships at the April 2027 production launch. The integration shape below is for planning purposes.

The Operator Web SDK is a React component library. Wire it against the sandbox by configuring its OperatorProvider with the sandbox base URL:

import { OperatorProvider, RightsRegistry, ProofCentre } from "@enfinitos/sdk-operator-web";

export function SandboxDashboard() {
  return (
    <OperatorProvider
      config={{
        apiBaseUrl: "https://sandbox.api.enfinitos.com/api/sandbox",
        authMode: "cookie",
        environment: "sandbox",
      }}
    >
      <RightsRegistry />
      <ProofCentre />
    </OperatorProvider>
  );
}

The sandbox API surfaces a subset of the production endpoints: rights, offers, challenges, proof, runtime-keys. Components that hit endpoints outside that subset (billing, pacing, pilot programmes) currently render an empty state when pointed at the sandbox. Wiring the remaining surfaces is on the post-launch roadmap.

@enfinitos/cli

The CLI has dedicated sandbox subcommands — see the CLI page for the full reference. The CLI itself ships at the April 2027 launch; today, use the published auditor SDK and the integration playground.

# Available at launch:
npm install -g @enfinitos/cli
enfinitos sandbox provision
enfinitos sandbox demo --count 12
enfinitos sandbox list
enfinitos sandbox get pak_xyz --save pack.json
enfinitos sandbox verify pack.json

Direct HTTP

Every SDK is a thin client over the same HTTP API. If you’d rather not adopt a client, the API is fully documented in the API reference and the snippets above translate to direct fetch calls one-to-one.

Webhooks

The key-authed /v1 surface (the same credentials as the quickstart) can also push events to you. Subscribe an HTTPS endpoint and the platform POSTs a signed payload for every matching tenant event — right.issued, offer.accepted, challenge.opened, delivery.observed, and the rest of the event taxonomy. ["*"] subscribes to everything; a few kinds are defined but don’t fire on the sandbox yet (right.resumed, right.expired, challenge.withdrawn, proof_pack.sealed, the key.* kinds) — subscribing to them is safe and forward-compatible.

Method + path	Purpose
`POST /v1/webhooks`	Subscribe: `{ url, events, label }`. `url` must be absolute `https`. Returns the `whsec_…` signing secret exactly once.
`GET /v1/webhooks`	List your subscriptions.
`GET /v1/webhooks/{subscriptionId}`	Fetch one subscription.
`DELETE /v1/webhooks/{subscriptionId}`	Permanently remove a subscription.
`POST /v1/webhooks/{subscriptionId}/active`	Pause / resume (`{ active: boolean }`) without rotating the secret.
`POST /v1/webhooks/{subscriptionId}/rotate-secret`	Issue a fresh secret, returned exactly once. The old secret dies immediately.
`GET /v1/webhooks/{subscriptionId}/deliveries`	List delivery attempts, newest first (`status` filter + cursor pagination).
`GET /v1/webhooks/{subscriptionId}/deliveries/{deliveryId}`	One delivery attempt with full payload and response excerpt.
`POST /v1/webhooks/{subscriptionId}/deliveries/{deliveryId}/replay`	Re-fire a delivery, signed with the current secret.
`POST /v1/webhooks/deliveries/process-due`	Process your due retries now (operator / external-cron hook).

Reads carry audit:read; the active toggle and replay additionally carry delivery:write; creating, deleting, rotating the secret, and process-due require a key carrying the wildcard * scope. Every delivery is signed with one header:

Enfinitos-Signature: t=<unix-seconds>,v1=<hex hmac-sha256>

where v1 is HMAC-SHA256 over `${t}.${body}` — the timestamp, a dot, the raw request body — keyed with your subscription’s whsec_… secret. Verify by recomputing the HMAC over exactly that string with your subscription secret and comparing; reject stale timestamps (say, older than five minutes) to block replayed captures:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifySignature(header: string, rawBody: string, secret: string) {
  const t = header.match(/t=(\d+)/)?.[1];
  const v1 = header.match(/v1=([0-9a-f]+)/)?.[1];
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // stale
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Delivery is asynchronous and at-least-once — make your receiver idempotent and return 2xx quickly (each attempt has a 10-second timeout). Failed attempts retry on an exponential backoff with jitter — roughly 30 s, 2 m, 10 m, 1 h — and after 5 attempts the delivery is marked dead_lettered: automatic retries stop, but the replay endpoint can re-fire it manually at any time.

What’s the same vs. production integration

Surface	Sandbox	Production
Auth	Cookie (`enf_sandbox_tenant`)	Bearer token + tenant scope
Base URL	`https://sandbox.api.enfinitos.com`	`https://api.enfinitos.com` (at April 2027 launch)
Rate limit	10 req/10s + 200/hour per IP	Per-tenant configurable
Idempotency keys	Not enforced	Required on mutating endpoints
Webhook backplane	Live — subscribe via `/v1/webhooks`	Same contract at launch
OAuth flow	Not used	Required for human reviewers

A buyer’s integration team can write their auditor SDK wiring against the sandbox today. Other SDKs ship at the April 2027 production launch — type definitions, response shapes, error codes, and state-machine semantics will be identical.

Get started

Concepts

SDKs

Sandbox

Compliance

@enfinitos/sdk-auditor

@enfinitos/sdk-brand

@enfinitos/sdk-operator-web

@enfinitos/cli

Direct HTTP

Webhooks

What’s the same vs. production integration

​@enfinitos/sdk-auditor

​@enfinitos/sdk-brand

​@enfinitos/sdk-operator-web

​@enfinitos/cli

​Direct HTTP

​Webhooks

​What’s the same vs. production integration

@enfinitos/sdk-auditor

@enfinitos/sdk-brand

@enfinitos/sdk-operator-web

@enfinitos/cli

Direct HTTP

Webhooks

What’s the same vs. production integration