AI agent steering

View as Markdown Open in ChatGPT Open in Claude

AI coding agents integrate the Checktiv Web SDK best when handed the rules and runnable recipes below. The same content ships inside the package so an agent finds it without the docs:

AGENTS.md and a machine-readable manifest.json ship in @checktiv/sdk-web, resolvable via the @checktiv/sdk-web/agents export. The manifest carries the module composition contract and the full code for every recipe below.
This page mirrors that content for humans and is included in the docs /llms-full.txt.

Rules

Prefer the zero-lifecycle Checktiv.mount entry. The simplest integration is two pieces of code. (1) On YOUR backend, call sessions.create({ templateId, applicant }, { idempotencyKey }) - a thin wrapper over POST /v1/sessions with your ah_sk_* secret key - and return ONLY the resulting clientToken to the browser. (2) In the browser, call Checktiv.mount(target, { fetchToken, onComplete }), where fetchToken returns that clientToken. fetchToken runs ONCE for the cold / new-device start, NOT on every expiry: the SDK exchanges the durable clientToken for a short-lived working token and refreshes it internally, so you write NO token-refresh endpoint, NO expiration handler, and NO resume endpoint. Key sessions.create idempotently per user or reservation so retries and new-device re-entry never double-bill. The legacy Checktiv.init({ ... }).mountProvisioned({ target }) with a getSessionToken browser-token callback stays fully supported for existing integrations.
The server mints the session, never the browser. Your backend calls the public API POST /v1/sessions with your secret key (ah_sk_*) and receives the session. The secret key is server-only: NEVER put ah_sk_* in browser code. To hand control to the frontend, your backend mints a short-lived browser token (bt_*) by calling POST /v1/sessions/{id}/browser_token with the same ah_sk_*; that route returns { data: { browser_token, expires_at } }. Only the bt_* string crosses to the browser.
Use mountProvisioned as the default path. Call Checktiv.init({ ... }).mountProvisioned({ target }). It reads the server-declared session.modules from GET /sdk/v1/sessions/me and renders exactly what the server composed, so the server drives composition. mount('idv') / mount('fraud') is the explicit override / escape hatch, not the first choice.
Completion is not a verdict: trust the signed webhook. The client event checktiv.idv.submitted is terminal-for-capture only; it means the applicant finished the capture step, NOT that they passed. The decision arrives on your server through the signed kyc.session.* webhook. Trust the signed webhook as the only outcome anchor; never infer a pass/fail from a client event.
Satisfy each applicant-info requirement once, through any one path. When a session declares applicant-info requirements (name, date of birth, address, and similar fields), each requirement is satisfied by ANY ONE of the supported collection paths, not by all of them. Supply a field through one path and the SDK treats that requirement as met; do not double-collect the same field. Let the server-declared session decide which fields are required rather than hard-coding a form.
Develop local-first with the synthetic driver. Use a test-mode publishable key (ah_pk_<region>_test_*) PLUS the synthetic opt-in. Test mode is selected by the key itself, not by a mode property on init. A test-mode key without the synthetic option renders a BLANK embed on a local origin because the capture license is domain-bound, whereas the synthetic path runs the full checktiv.idv.* flow locally with no camera, no license, and no deployed environment. Ensure your own session-mint backend and token endpoint are running before the SDK calls getSessionToken. Build and verify locally with the synthetic driver, then graduate to a deployed environment for real capture and ship through the standard npm / CDN path.
getSessionToken supplies a fresh bt_ on demand.* getSessionToken is string | ((ctx: { sessionId; reason: 'initial' | 'expired' | '401' }) => Promise<string>). The SDK calls it on mount and again on expiry or a 401, then retries the failed request once. Always return a freshly minted bt_* from your backend; never hold a long-lived credential in the browser. If your callback rejects, the SDK emits token_expired with recovery: 'refresh_session' and halts cleanly.
Add your frontend origin to the publishable key allowlist first. Each publishable key carries an origin allowlist that you set in the console / dashboard. Your frontend’s origin MUST be on that allowlist before the first mount, or EVERY mount fails with origin_not_allowed (the bt_* data-plane routes reject an off-allowlist Origin). Add your origin to the publishable key allowlist before you integrate.
The SDK adds X-Publishable-Key itself on the customer path. Pass publishableKey to Checktiv.init(...) and stop there. On the customer (pk-present) path the managed transport attaches the X-Publishable-Key header to its own bt_* data-plane calls internally. Do NOT also hand-add an X-Publishable-Key header yourself; double-adding it is wrong. (The first-party hosted path used internally by the verify app carries no publishable key and sends none.)
Cross-device QR handoff is built into the managed IDV module. Cross-device handoff (a desktop applicant finishes on their phone via a QR + copy-link overlay) is OWNED BY THE MANAGED IDV MODULE. Render it with client.mount('idv', { crossDeviceCopy, onEvent }) and the returned handle exposes openCrossDevice(): calling it opens the overlay OVER the still-live capture frame, runs the completion poll, and emits checktiv.idv.submitted when the phone finishes so your host reloads. You MUST import '@checktiv/sdk-web/idv/cross-device'; to enable the overlay (the CDN script-tag bundle already includes it); without that import openCrossDevice() is a graceful, actionable no-op, as it also is before the applicant verification resolves or when no crossDeviceCopy was supplied. IdvMountOptions carries crossDeviceCopy (host-injected strings; the unavailableMessage key is required so no arm renders blank) and the OPTIONAL onOpenCrossDevice mint override; IdvHandle exposes openCrossDevice?(), so call it as handle.openCrossDevice?.(). NOTE: mountProvisioned and the zero-lifecycle Checktiv.mount entry do NOT expose the overlay: use the explicit mount('idv', ...) call when you need openCrossDevice().

Who mints the one-time handoff link depends on the token plane: • Working-token plane: the module mints the link ITSELF (it calls its own handoff endpoint POST /sdk/v1/sessions/me/handoff, authenticated by the applicant’s short-lived working token, and caps the per-overlay “refresh link” re-mints). Supply onOpenCrossDevice ONLY to point the mint at your own backend instead. • Browser-token (bt_*) plane: the SDK CANNOT self-mint (the handoff route rejects a bt_* bearer), so you MUST supply onOpenCrossDevice backed by a server-held credential.

onOpenCrossDevice: CrossDeviceHandoffHook is () => Promise<{ kind: 'ok'; url: string } | { kind: 'unavailable' }>. Return { kind: 'ok', url } with the journey URL (which MUST be https:: the SDK collapses javascript:, http:, and data: schemes to 'unavailable') or { kind: 'unavailable' } when the mint fails. The hook is re-callable for the overlay’s “refresh link” affordance; the SDK caps re-mints per overlay.

For a FULLY CUSTOM IDV renderer built on @checktiv/sdk-web/capture (NOT the managed module), the STANDALONE exports drive the overlay yourself and you always supply the mint hook: @checktiv/sdk-web/idv/cross-device (openCrossDeviceOverlay(opts) opens the overlay, preloadCrossDeviceChunk() warms the lazy chunk) and @checktiv/sdk-web/cross-device (mountCrossDevice(target, props) renders the bare panel on a screen you fully control). openCrossDeviceOverlay takes { target, onOpenCrossDevice, copy, isMobile, emit, onClose } plus an optional poll config, and returns a handle with setCompleting() (keep the QR mounted with a waiting label while your page reloads) and destroy() (idempotent). Set isMobile: true to suppress the QR on a phone (a same-device scan is circular). The SDK NEVER writes window.location; navigation is always the host’s, off the emitted event.

Three token-free overlay events (NONE carries the url / OTL / short-code / expiry hint): • checktiv.idv.cross_device_opened: the mint returned ok and the overlay is shown. • checktiv.idv.cross_device_unavailable: the mint returned unavailable or URL validation failed. • checktiv.idv.cross_device_capped: the completion poll hit its total time cap without the phone finishing. NOT an error and NOT a verdict: the QR panel stays mounted so the applicant can still finish on their phone.

Runnable recipes

The full, copy-pasteable code for each step ships in the package manifest (@checktiv/sdk-web/agents):

(e) Zero-lifecycle: sessions.create on the backend, Checktiv.mount on the frontend
(a) Backend: mint a session with your secret key
(b) Backend: mint a bt_ browser token and hand it to the frontend*
(c) Frontend: init and mountProvisioned
(d) Backend: verify the signed webhook (HMAC) - the only outcome anchor