Local Bridge API Contract
The stable loopback HTTP API exposed by the SecuGen Connect runtime for browser-based fingerprint capture. Web apps integrate once against this contract and run unchanged on Windows, Linux, and Android.
Quick summary
- Base URL (default):
http://127.0.0.1:4499on mainstream Windows/Linux installs, with fallback through4498-4494if the default port is busy; HTTPS fallback remains configurable - SecuGen Connect Protocol v1 discovery:
SGDISC /v1/discoverconfirms the bridge during bounded port scanning; operational APIs stay REST/JSON - API prefix:
/v1 - Security: loopback-only · origin allowlist · short-lived session token
- Capture: requires a server-issued
nonce(anti-replay) - Browser networking: CORS preflight + Private Network Access (PNA) preflight supported
1. Transport & binding
Default binding
The runtime binds to loopback only by default — no LAN exposure. Default port is 4499, with a controlled fallback through 4498-4494 only when the default port is busy. The listen address remains configurable via admin / deployment tooling.
HTTP loopback mainstream policy
Mainstream Windows/Linux deployments use HTTP on loopback by default to avoid Local-CA trust prompts. The runtime remains loopback-only and keeps Origin allowlist, session-token, nonce, rate-limit, CORS, and Private Network Access controls enabled. HTTPS/TLS remains available as an explicit enterprise or macOS fallback.
Hostnames
Recommended host is 127.0.0.1. The runtime may also accept localhost and ::1 as equivalents.
2. CORS & Private Network Access
All endpoints must handle OPTIONS preflight requests. CORS headers are returned only when the request Origin matches the configured allowlist.
| Header | Notes |
|---|---|
Access-Control-Allow-Origin | Echoes the request Origin (no wildcard in production). |
Vary | Must include Origin. |
Access-Control-Allow-Methods | SGDISC, GET, POST, PATCH, DELETE, OPTIONS where supported; SGDISC is discovery-only. |
Access-Control-Allow-Headers | Includes Content-Type, Authorization, plus any custom headers. |
Access-Control-Allow-Credentials | Only when relying on cookies / credentials. |
Access-Control-Allow-Private-Network | Returns true on preflight when the request includes Access-Control-Request-Private-Network: true. |
3. Authentication model
The runtime must not be callable by arbitrary websites. The minimum security model is:
- Origin allowlist (install-time or admin policy)
- Short-lived session token via
POST /v1/session/start - Server-issued nonce required for sensitive operations (template return)
Calls that require a session token must include:
Authorization: Bearer <sessionToken>4. Common types
4.1 TemplateFormat
ANSI378(recommended default)ISO19794_2SG400
4.2 Quality
quality is an integer in the range 0..100, intended to align with SecuGen SDK image-quality scoring.
4.3 Standard response shapes
Success
{
"ok": true,
"apiVersion": "2026-02-05"
}Error
{
"ok": false,
"apiVersion": "2026-02-05",
"error": "low_quality",
"message": "quality=42, minQuality=50",
"details": {
"sdkErrorCode": 123,
"hint": "Ask the user to reposition their finger"
}
}5. Endpoints
5.0 SGDISC /v1/discover
SecuGen Connect Protocol v1 discovery. Browser and SDK callers use this custom method while scanning 4499, then 4498-4494, to confirm the responder is SecuGen Connect before calling the standard REST API. The response is metadata-only and never includes biometric payloads.
{
"ok": true,
"apiVersion": "2026-02-08",
"product": "SecuGen Connect",
"protocol": "secugen-connect/1",
"method": "SGDISC",
"transport": "http",
"listenAddr": "127.0.0.1:4499",
"baseUrl": "http://127.0.0.1:4499",
"portRange": { "start": 4494, "end": 4499, "primary": 4499,
"fallbackOrder": [4499, 4498, 4497, 4496, 4495, 4494] }
}5.1 GET /v1/health (alias GET /ping)
Returns whether the bridge service is running and provides a compatibility marker.
{
"ok": true,
"product": "SecuGen Connect",
"version": "1.0.0",
"apiVersion": "2026-02-05"
}5.2 GET /v1/info (alias GET /device-info)
Returns runtime, update status, and device information.
{
"ok": true,
"apiVersion": "2026-02-05",
"runtime": {
"version": "1.0.0",
"os": "windows|linux|android",
"https": true,
"port": 4499
},
"update": {
"enabled": true,
"status": "up_to_date|update_available|error|disabled",
"channel": "stable|beta|local",
"currentVersion": "1.0.0",
"latestVersion": "1.0.1",
"updateAvailable": false,
"signatureVerified": true,
"lastCheckedAt": "2026-02-05T00:00:00Z"
},
"capabilities": {
"templateFormats": ["ANSI378", "ISO19794_2", "SG400"],
"returnImage": true
},
"devices": [
{ "id": "0", "model": "HU20-A", "serial": "XXXX", "status": "ready" }
]
}5.3 GET /v1/diagnostics
A safe troubleshooting payload — runtime + config snapshot + session stats. Must never include biometric payloads (templates / images).
{
"ok": true,
"apiVersion": "2026-02-05",
"time": "2026-02-05T00:00:00Z",
"runtime": {
"version": "1.0.0",
"os": "windows|linux|android",
"https": true, "port": 4499,
"arch": "amd64", "go": "go1.22.x", "pid": 1234
},
"config": { "cors": { "allowedOrigins": ["http://localhost:5173"] }, "session": { "ttlMs": 60000 } },
"sessions": { "active": 1, "purgedExpired": 0, "ttlMs": 60000 },
"update": { "enabled": true, "status": "up_to_date", "currentVersion": "1.0.0" },
"devices": [],
"endpoints": ["/v1/health", "/v1/info", "/v1/diagnostics"]
}5.4 POST /v1/session/start
Starts a short-lived session after validating the request origin.
Request
{
"client": { "name": "web-sdk", "version": "0.1.1" }
}Response (200)
{
"ok": true,
"apiVersion": "2026-02-05",
"sessionToken": "<opaque>",
"expiresInMs": 60000
}5.5 POST /v1/session/end
Optional — ends the session early.
5.6 POST /v1/fingerprint/capture (alias POST /capture)
Captures a fingerprint and returns a template (and optionally an image, when policy + the request both allow it).
Request
{
"nonce": "server-issued-nonce",
"timeoutMs": 10000,
"minQuality": 50,
"templateFormat": "ANSI378",
"returnImage": false,
"smartCapture": true,
"blinkLed": true,
"touchGate": true,
"deviceId": "0"
}Response (200)
{
"ok": true,
"apiVersion": "2026-02-05",
"nonce": "server-issued-nonce",
"quality": 78,
"templateFormat": "ANSI378",
"templateBase64": "<base64>",
"image": {
"encoding": "png",
"mime": "image/png",
"width": 260, "height": 300, "dpi": 500,
"dataBase64": "<base64>"
},
"device": { "model": "HU20-A", "serial": "XXXX" },
"ts": "2026-02-05T15:04:05Z"
}image is optional and returned only when returnImage=true and the capture runtime can supply image bytes.
6. Standard error codes
These codes are part of the product contract.
| Code | Meaning |
|---|---|
invalid_request | Missing / invalid JSON fields. |
origin_not_allowed | Request origin not in the allowlist. |
session_required | Missing session token for a protected endpoint. |
session_expired | Session token expired or invalid. |
nonce_invalid | Missing / invalid / expired / reused nonce. |
bridge_not_ready | Runtime up, but SDK / device not ready. |
device_not_found | No compatible device detected. |
permission_denied | Permission rejected (common on Android USB). |
capture_in_progress | Another capture request is already running. |
timeout | Timed out waiting for an acceptable image. |
low_quality | Captured quality below minQuality. |
unsupported_template_format | Requested format not supported by runtime / device. |
sdk_error | Vendor SDK returned an error (see details.sdkErrorCode). |
7. Versioning policy
The URL prefix (/v1) is the major API version. apiVersion is a date string (YYYY-MM-DD) that tracks contract revisions within the major version. Breaking changes ship as a new major (/v2) with a new apiVersion. Clients must ignore unknown fields to allow forward-compatible additions.