SureClock
SureClock
Overview
Developer Reference

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:

pk_live_... (Publishable Key)Safe for Frontend Kiosks

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.

sk_live_... (Secret Key)Keep Server-Side & Protected

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:

bash
npm install @karalasoft/face-attendance-kiosk

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

tsx
"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.

tsx
"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:

tsx
// 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 />

PropTypeRequiredDescription
api_keystringYesPublishable key (pk_live_...)
workspace_idstringYesWorkspace slug for attendance tracking
titlestringNoHeading text displayed above camera viewfinder
apiUrlstringNoEngine endpoint URL override
onSuccess(res: AttendanceSuccessResult) => voidNoFires upon 1:N match above 90% confidence
onError(err: string) => voidNoFires on camera denial or unverified check-in

<FaceEnrollment />

PropTypeRequiredDescription
api_keystringYesSecret key (sk_live_...)
workspace_idstringYesTarget workspace for face vector storage
employee_idstringNoPre-fill employee ID; omit to let user enter it
onSuccess(res: EnrollmentSuccessResult) => voidNoFires when face vector is saved successfully

REST API Reference (cURL)

All API endpoints authenticate via the x-api-key request header.

POST/api/v1/workspaces

Provisions an isolated workspace. Requires sk_live_....

bash
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"
  }'
POST/api/v1/faces/register

Registers an employee face vector. Requires sk_live_....

bash
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..."
  }'
POST/api/v1/attendance/verify

Performs a 1:N kiosk search. Accepts pk_live_... (Publishable Key).

bash
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):

json
{
  "match": true,
  "employee_id": "EMP_0412",
  "confidence": 0.9421,
  "timestamp": "2026-11-19T09:02:14.812Z",
  "message": "Clock-in verified"
}
GET/api/v1/attendance/logs

Queries scoped clock-in logs for reporting. Requires sk_live_....

bash
curl -X GET "https://api.sureclock.com/api/v1/attendance/logs?workspace_id=branch-dhaka&limit=50" \
  -H "x-api-key: sk_live_8f3a9e2d1c0b4a78129f"
DELETE/api/v1/employees/{employee_id}

GDPR Right to Erasure: Permanently removes the employee face vector. Requires sk_live_....

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

Need architectural support or enterprise deployment guidance?Contact Engineering Support →