SecuGen Connect Developer Guide
Developer Guide · Core

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.

Who this guide is for. Developers building new biometric features on SecuGen Connect, and teams migrating an existing FDxSDK / WebAPI / JSGFPLib application onto the new bridge.

1. Why SecuGen Connect

SecuGen Connect ships a single, cross-platform local bridge service exposed on http://127.0.0.1:4499 for mainstream Windows/Linux installs, with HTTPS fallback where required. A web app, native app, or service integrates against this stable HTTP contract once, and the same code runs on Windows, macOS, Linux, and Android. Server-side licensing, seat governance, and offline-grace are managed for you by the license server.

Replaces three legacy SDKs

Legacy SDKPlatformTypical user
FDxSDK ProWindows (C / C++ / C# / Java)Server & desktop native apps
SecuGen WebAPIWindows (HTTP localhost:8000)Browser-based apps
JSGFPLibBrowser (JavaScript)Web frontends calling capture/match directly

2. Architecture at a glance

SecuGen Connect is layered. 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. Drop in the shim today, move to the canonical API on your own schedule.
  3. Single runtime. Every wrapper, regardless of platform, talks to the same bridge on 127.0.0.1:4499.
  4. JavaScript / TypeScript first. Browser usage is the dominant 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 call into 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

Drop in the WebAPI shim (secugen-webapi-shim.js) before your existing demo script. The shim intercepts XMLHttpRequest / fetch and rewrites localhost:8000 / localhost:8443 calls to the Connect bridge. Existing capture / match callbacks keep working unchanged.

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 plumbing.

Existing JSGFPLib customers

Load the JSGFPLib compatibility layer alongside the shim. The legacy globals — CallSGIFPCapture, CallSGIMatchScore, CheckSGConnect — are exposed with their original signatures, but they call the Connect bridge under the hood.

New customers

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

5. Where to go next