SureClock Developer Documentation
SureClock provides zero overhead, client side biometric React components and cloud APIs. It allows development teams to drop production grade 1:N facial attendance kiosks and HR enrollment terminals into web dashboards with zero backend computer vision infrastructure.
<FaceAttendanceKiosk />
Touchless check-in terminal with camera stream, canvas compression (~40 KB), auditory chime, and instant 1:N vector verification.
<FaceEnrollment />
HR registration tool with automatic face centering, capture snapshot, and immediate 128D mathematical vector generation.
The Dual-Key Security Architecture
Every tenant platform is provisioned with two distinct keys. Understanding this separation guarantees security across client kiosks and backend services:
Use this key in client-side React views with <FaceAttendanceKiosk />. It is strictly limited to 1:N attendance clock-in verification. The engine automatically rejects any administrative, enrollment, or deletion requests using this key.
Use this key for privileged operations: provisioning workspace slugs, registering employee faces with <FaceEnrollment />, querying attendance history, and executing GDPR employee removals.
Need API Keys for Local Development?
Generate a free sandbox pair of publishable and secret keys in 10 seconds.
Installation
Install the official React SDK package from the registry:
npm install @karalasoft/face-attendance-kiosk1. <FaceAttendanceKiosk /> (Clock-In Station)
The attendance kiosk provides a high-density, touchless biometric check-in experience. It captures video frames, compresses them via HTML5 Canvas to ~40 KB, and dispatches them to the verification engine.
"use client";
import { FaceAttendanceKiosk } from "@karalasoft/face-attendance-kiosk";
export default function AttendanceStation() {
return (
<main className="min-h-screen grid place-items-center bg-[#080d1a] p-6">
<FaceAttendanceKiosk
api_key={process.env.NEXT_PUBLIC_SURECLOCK_PK!} // Use publishable key
workspace_id="branch-dhaka"
title="Reception Attendance Kiosk"
onSuccess={(result) => {
console.log(`Verified ${result.employee_id} at ${result.timestamp}`);
console.log(`Match confidence: ${(result.confidence * 100).toFixed(1)}%`);
}}
onError={(err) => {
console.warn("Clock-in unverified:", err);
}}
/>
</main>
);
}2. <FaceEnrollment /> (Staff Registration)
The enrollment component allows HR staff to register employees. It features an interactive camera reticle, capture snapshot review, employee ID input, and instant mathematical vector extraction.
"use client";
import { FaceEnrollment } from "@karalasoft/face-attendance-kiosk";
export default function StaffEnrollmentPage() {
return (
<main className="min-h-screen grid place-items-center bg-[#080d1a] p-6">
<FaceEnrollment
api_key={process.env.SURECLOCK_SECRET_KEY!} // Secret key required for enrollment
workspace_id="branch-dhaka"
employee_id="EMP_0412" // Optional pre-filled ID, or omit to allow user input
title="Employee Biometric Registration"
onSuccess={(result) => {
alert(`Employee ${result.employee_id} successfully enrolled in ${result.workspace_id}`);
}}
onError={(err) => {
console.error("Enrollment failed:", err);
}}
/>
</main>
);
}Next.js App Router Integration
Because camera access (navigator.mediaDevices.getUserMedia) is a browser API, dynamically import the kiosk components with SSR disabled to guarantee hydration safety:
// components/DynamicKiosk.tsx
"use client";
import dynamic from "next/dynamic";
export const DynamicKiosk = dynamic(
() => import("@karalasoft/face-attendance-kiosk").then((m) => m.FaceAttendanceKiosk),
{
ssr: false,
loading: () => (
<div className="p-8 text-center text-slate-400 font-mono">
Connecting to camera sensor...
</div>
),
}
);Component Props Reference
<FaceAttendanceKiosk />
| Prop | Type | Required | Description |
|---|---|---|---|
| api_key | string | Yes | Publishable key (pk_live_...) |
| workspace_id | string | Yes | Workspace slug for attendance tracking |
| title | string | No | Heading text displayed above camera viewfinder |
| apiUrl | string | No | Engine endpoint URL override |
| onSuccess | (res: AttendanceSuccessResult) => void | No | Fires upon 1:N match above 90% confidence |
| onError | (err: string) => void | No | Fires on camera denial or unverified check-in |
<FaceEnrollment />
| Prop | Type | Required | Description |
|---|---|---|---|
| api_key | string | Yes | Secret key (sk_live_...) |
| workspace_id | string | Yes | Target workspace for face vector storage |
| employee_id | string | No | Pre-fill employee ID; omit to let user enter it |
| onSuccess | (res: EnrollmentSuccessResult) => void | No | Fires when face vector is saved successfully |
REST API Reference (cURL)
All API endpoints authenticate via the x-api-key request header.
/api/v1/workspacesProvisions an isolated workspace. Requires sk_live_....
curl -X POST https://api.sureclock.com/api/v1/workspaces \
-H "x-api-key: sk_live_8f3a9e2d1c0b4a78129f" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "branch-dhaka",
"name": "Dhaka Main Showroom"
}'/api/v1/faces/registerRegisters an employee face vector. Requires sk_live_....
curl -X POST https://api.sureclock.com/api/v1/faces/register \
-H "x-api-key: sk_live_8f3a9e2d1c0b4a78129f" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "branch-dhaka",
"employee_id": "EMP_0412",
"image_base64": "/9j/4AAQSkZJRgABAQ..."
}'/api/v1/attendance/verifyPerforms a 1:N kiosk search. Accepts pk_live_... (Publishable Key).
curl -X POST https://api.sureclock.com/api/v1/attendance/verify \
-H "x-api-key: pk_live_4e7b8c9a1d2f3e4a5b6c" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "branch-dhaka",
"image_base64": "/9j/4AAQSkZJRgABAQ..."
}'Response (200 OK):
{
"match": true,
"employee_id": "EMP_0412",
"confidence": 0.9421,
"timestamp": "2026-11-19T09:02:14.812Z",
"message": "Clock-in verified"
}/api/v1/attendance/logsQueries scoped clock-in logs for reporting. Requires sk_live_....
curl -X GET "https://api.sureclock.com/api/v1/attendance/logs?workspace_id=branch-dhaka&limit=50" \
-H "x-api-key: sk_live_8f3a9e2d1c0b4a78129f"/api/v1/employees/{employee_id}GDPR Right to Erasure: Permanently removes the employee face vector. Requires sk_live_....
curl -X DELETE "https://api.sureclock.com/api/v1/employees/EMP_0412?workspace_id=branch-dhaka" \
-H "x-api-key: sk_live_8f3a9e2d1c0b4a78129f"Biometric Security & GDPR Compliance
SureClock enforces a strict zero raw photo retention policy:
Irreversible 128D Vectors
Enrolled faces exist solely as normalized 128-dimensional floating point vectors. These mathematical coordinates cannot be reverse engineered to reconstruct an image.
Immediate Buffer Purge
During verification, the ~40 KB camera buffer is ingested in memory, projected through the inference model, and immediately wiped. Photos are never stored on disk.
Troubleshooting
Camera Access Blocked (NotAllowedError)
Web browsers require HTTPS for camera device access. In local development, use http://localhost:3000. In staging and production, ensure an SSL certificate is active.
Low Confidence Rejection
The engine default confidence threshold is 90% (0.90). To minimize false rejections, position cameras away from strong backlights (e.g. windows behind the subject) and instruct employees to look directly into the viewfinder.