SecuGen Connect — Developer Guide

SecuGen Connect is the next-generation biometric bridge that replaces FDxSDK Pro, the legacy SecuGen WebAPI, and JSGFPLib. This guide covers the integration model, architectural layers, and the path to migrate existing applications with minimal code change.

1. Why SecuGen Connect

SecuGen Connect provides a single, cross-platform local bridge service. On mainstream Windows/Linux installs, it is available at http://127.0.0.1:4499, with HTTPS fallback where required. A web app, native app, or service integrates with this stable HTTP contract once. The same code then runs on Windows, macOS, Linux, and Android. The License Server manages server-side licensing, seat governance, and offline-grace for you.

Replaces three legacy SDKs

2. Architecture at a glance

SecuGen Connect is built in layers. Existing code talks to a thin compatibility wrapper. The wrapper talks to the canonical client. The canonical client talks to the local bridge. The bridge talks to the SecuGen device through a vendor adapter.

Design principles

1. Minimize code change. Function names, callback patterns, and response shapes from the legacy SDKs are preserved by the wrappers wherever possible.
2. Progressive migration. Add the shim today. Move to the canonical API later, on your own schedule.
3. Single runtime. Every wrapper, on every platform, talks to the same Connect Bridge at 127.0.0.1:4499.
4. JavaScript / TypeScript first. Browser use is the most common case. The JS SDK is the reference implementation.

3. Quick start (web app)

1. Discover the bridge. SGDISC /v1/discover → expect SecuGen Connect Protocol v1 metadata; keep GET /v1/health as a legacy fallback.
2. Probe readiness. GET /v1/health → expect HTTP 200 with {"ok":true}.
3. Start a session. POST /v1/session/start → returns a short-lived sessionToken (default TTL 60 s).
4. Capture a fingerprint. POST /v1/fingerprint/capture with Authorization: Bearer <sessionToken>, a server-issued nonce, and template-format options.
5. Verify on your server. Send the returned template to your application backend and let it apply your authentication policy.

// Minimal sketch — see the dedicated bridge contract for full schemas
const discovery = await fetch('http://127.0.0.1:4499/v1/discover', {
  method: 'SGDISC',
}).then(r => r.json());
if (discovery.protocol !== 'secugen-connect/1') throw new Error('wrong_bridge');

const health = await fetch('http://127.0.0.1:4499/v1/health').then(r => r.json());
if (!health.ok) throw new Error('bridge_not_running');

const session = await fetch('http://127.0.0.1:4499/v1/session/start', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ client: { name: 'demo', version: '1.0.0' } }),
}).then(r => r.json());

const cap = await fetch('http://127.0.0.1:4499/v1/fingerprint/capture', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${session.sessionToken}`,
  },
  body: JSON.stringify({
    nonce: serverIssuedNonce,
    timeoutMs: 10000,
    minQuality: 50,
    templateFormat: 'ANSI378',
    smartCapture: true,
    blinkLed: true,
    touchGate: true,
  }),
}).then(r => r.json());

if (cap.ok) postToServer(cap.templateBase64);

4. Migration paths

Existing WebAPI customers

Install Connect Bridge and keep the existing WebAPI calls. Its native HTTPS compatibility listener serves the legacy SGIFPCapture and SGIMatchScore contract on https://localhost:8443. This means existing capture and match callbacks continue to work without a shim or endpoint rewrite.

Existing FDxSDK Pro customers

Use the FDxSDK-style wrapper: the shared C API (Linux / macOS / Windows) or the Android JSGFPLib class, with Init / OpenDevice / GetImage / CreateTemplate / MatchTemplate / CloseDevice. The wrapper hides session management, authentication, and HTTP transport details.

Existing JSGFPLib customers

Load the JSGFPLib compatibility layer alongside the shim. The legacy globals (CallSGIFPCapture, CallSGIMatchScore, CheckSGConnect) are available with their original signatures, but internally they call Connect Bridge.

New customers

Use the canonical client @secugen/connect-sdk directly. It provides a typed, promise-based API. It is also the reference target that the wrappers translate to.

5. Where to go next

• Local Bridge API Contract — full endpoint schema, error codes, versioning policy.
• Browser Integration Guide — CORS, Private Network Access, HTTP loopback, HTTPS fallback, browser quirks.
• Native SDK Wrapper Guide — the shared C-API wrappers (Linux / macOS / Windows) and the Android Java wrapper for FDxSDK-style apps.