Short-lived Cloud sessions

Cloud v2 is the only supported API. The browser needs a publishable key and a short-lived widget token. A trusted customer backend authorizes the user and chooses the importer, destination, origin, and limits.

The adapter is implemented locally. Public package release, production identity setup, destination approval, and hosted activation are separate requirements.

Three credential boundaries

1. Cloud administrators use an identity-provider access token to configure a project and environment, register an exact browser origin, and publish an immutable importer version.
2. Your backend uses an environment server key to mint a session for an authorized application user. The destination must be registered and its HTTPS origin approved by the service operator.
3. The widget uses its session token in the Authorization header plus its publishable key in X-Convert-Buddy-Key. It can access only its pinned configuration and imports.

1. Mint on your backend

This integration template assumes your application has already authenticated and authorized its user. Supply your own authorization, CSRF protection, trusted configuration, and session-ownership storage; it is not an unauthenticated proxy endpoint.

// In your authenticated backend only.
// Run your application's authorization and CSRF checks first.
// IDs, origin, and budgets come from trusted server configuration.
const response = await fetch(
  new URL('/v2/server/widget-sessions', process.env.CB_API_URL),
  {
    method: 'POST',
    redirect: 'error',
    cache: 'no-store',
    headers: {
      authorization: 'Bearer ' + process.env.CB_SERVER_KEY,
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      importerId: config.importerId,
      publishableKeyId: config.publishableKeyId,
      destinationId: config.destinationId,
      origin: config.applicationOrigin,
      expiresInSeconds: 900,
      maxImports: 3,
      maxBytes: 33554432,
      maxRecords: 100000,
    }),
  },
);
if (!response.ok) throw new Error('Import authorization failed');
const grant = await response.json();
// Persist user ID → sessionId ownership on YOUR backend before
// responding. Never persist or log the token.
return Response.json(
  { sessionId: grant.sessionId, token: grant.token },
  { headers: { 'Cache-Control': 'no-store' } },
);

Do not forward browser-selected destinations, IDs, or budgets. Never put the server key in a public environment variable or browser bundle.

2. Provide sessions to the importer

Implement your application's /api/import-session endpoint, then supply getSession. The browser keeps tokens in memory, outside URLs, logs, telemetry, and persistent storage.

import { Importer } from '@diakrio/importer-react';
import '@cloudflare/kumo/styles/standalone';
import '@diakrio/importer-react/styles.css';

<Importer
  mode="api"
  apiUrl={publicConfig.apiUrl}
  publishableKey={publicConfig.publishableKey}
  getSession={async ({ sessionId, signal }) => {
    const response = await fetch('/api/import-session', {
      method: 'POST',
      credentials: 'same-origin',
      cache: 'no-store',
      signal,
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ sessionId }),
    });
    if (!response.ok) throw new Error('Import authorization failed');
    return response.json();
  }}
/>

For lower-level integrations, ConvertBuddyWidgetClient exposes config, import creation, batch delivery, status, completion, and cancellation. Use the React quickstart for package prerequisites.

3. Deliver and acknowledge

Imports use a stable UUID client key. Each batch carries a stable batch ID and records, with a maximum of 10,000 records and 2 MiB for the complete JSON envelope. Session byte budgets measure outgoing normalized batches, not the original file size.

The destination must verify the timestamped HMAC signature using verifyDeliverySignatureV1 and DELIVERY_HEADERS from the contracts package. Deduplicate the import ID and batch ID durably before side effects. Retrying requires identical serialized bytes.

Only a matching delivered or duplicate receipt is an acknowledgement. BATCH_IN_FLIGHT and DELIVERY_UNCERTAIN require a bounded retry with the same identity. A timeout may occur after the destination accepted the batch. Delivery is at-least-once.

Expiry, renewal, and cancellation

Grants default to 15 minutes; the allowed lifetime is 60–3600 seconds. When the importer asks for an existing session ID, your backend must reauthorize the user and verify ownership before calling POST /v2/server/widget-sessions/:sessionId/renew with { expiresInSeconds: 900 }.

Renewal rotates the token within the original 24-hour horizon and preserves the version, destination, quotas, and receipts. The old token becomes invalid. Removed origins, revoked credentials, archived importers, and disabled destinations remain denied. Never substitute a new session for a resumed import.

Opt-in device drafts store source data and progress locally, without tokens. Browser eviction, revocation, and the renewal horizon can prevent recovery. Completion waits for all submitted receipts; cancellation stops future work but cannot recall delivered records.

Current boundaries

Importer routes accept validated record batches rather than original files. Hosted OCR uses a separate authenticated image endpoint, disabled until configured per environment. Anonymizer processing remains unavailable. AI field mapping is available when enabled for the environment and published importer: up to 30 sampled records transit Cloud and Workers AI, followed by local validation and review. Deterministic mapping remains available if AI fails. Server SDK calls also require an explicit mapping permission. Review the processing and privacy boundary, or read the v1 migration notes.