Base URL: https://auraid.pro (or http://localhost:3000 locally). Auth via x-api-key header. All bodies are JSON. Frames are JPEG base64 data-URLs from the liveness SDK.
POST /api/v1/enroll
x-api-key: aura_live_...
{
"endUserId": "user_123",
"frame": "data:image/jpeg;base64,/9j/..."
}
-> { "status": "success" }
# The frame MUST contain a detectable face.
# Otherwise: 422 { "status": "failed",
# "reason": "No face Detected ...", "code": "NO_FACE" }POST /api/v1/verify-pipeline
x-api-key: aura_live_...
{
"endUserId": "user_123",
"frames": ["data:...", "data:...", "data:..."],
"expected_challenges": ["NORMAL","LOOK_LEFT","NOD"]
}
—†’ {
"verified": true,
"liveness_passed": true,
"confidence": 0.913,
"reason": "Success"
}
// No detectable face in any frame -> 422, never a misleading mismatch:
{ "verified": false, "liveness_passed": false, "confidence": 0,
"reason": "No face Detected ...", "code": "NO_FACE" }
// Photo / screen / replay attack -> verified:false + SPOOF_* code.
// Same response shape — no reintegration needed, just handle verified:false:
{ "verified": false, "liveness_passed": false, "confidence": 0,
"reason": "No movement between frames ...", "code": "SPOOF_STILL" }
// Codes: SPOOF_FLAT (print-like) · SPOOF_SCREEN (display banding/pattern)
// SPOOF_BORDER (phone/paper edge) · SPOOF_STILL (no inter-frame motion)
// SPOOF_CHALLENGE (face never turned) · SPOOF_COLOR · SPOOF_UNREADABLE.
// Rule: send 3-4 DISTINCT frames from the guided steps (forward/turns/nod).
// Never send the same frame repeated — it is correctly rejected as SPOOF_STILL.POST /api/v1/verify-pipeline
{ ..., "voice": true }
-> { ..., "voice_prompts": {
"verified": "Identity verified. Welcome back.",
"rejected": "Verification failed. Please try again."
} }
# Vocalize in your capture UI (Web Speech API):
speechSynthesis.speak(
new SpeechSynthesisUtterance(j.voice_prompts.verified));
// Default is silent - omit "voice" or pass voice:false.
// Enroll accepts voice:true too (returns the full
// forward/left/right/nod/enrolled script).const res = await fetch(base + '/api/v1/verify-pipeline', {
method: 'POST',
headers: { 'x-api-key': process.env.AURAID_KEY,
'Content-Type': 'application/json' },
body: JSON.stringify({ endUserId, frames })
});import requests
r = requests.post(base + '/api/v1/enroll',
headers={'x-api-key': KEY},
json={'endUserId': uid, 'frame': data_url})
print(r.json())$ch = curl_init($base.'/api/v1/verify-pipeline'); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: $key", "Content-Type: application/json"]); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([ 'endUserId' => $uid, 'frames' => $frames]));
Drop our capture widget into your signup/login page and your users get exactly the auraid.pro/demo experience: same 4 guided steps, same US-English voice prompts, same progress ring, same auto-capture, same low-light guard. No face thumbnails — frames go straight to your backend, which calls our API with your key.
<div id="auraid-capture"></div>
<script src="https://auraid.pro/auraid-capture.js"></script>
<script>
AuraIDCapture.mount('#auraid-capture', {
baseUrl: 'https://your-backend.example', // YOUR proxy (keeps the API key secret)
endUserId: 'user_123',
voice: true, // spoken prompts, on by default
onDone: ({verified, confidence, reason}) => {
if (verified) location.href = '/welcome';
else alert('Verification failed (' + confidence + ') — try again');
}
});
</script>Your proxy forwards to POST /api/v1/enroll (first frame) and POST /api/v1/verify-pipeline (all frames) with x-api-key. Never expose the key in the browser. Steps, timings (3s/4s/4s/4s), voice lines and the light gate (brightness < 52 → pause + warning, API returns LOW_LIGHT) match the demo 1:1.
Open live demoPrefer to build your own UI? Use /demo as reference. Guide the user through face-forward, head-turn and nod prompts, capture one frame per prompt, then POST the frames.
Our billing provider notifies POST /api/billing/ipn on payment events. A confirmed payment activates the subscription for 12 months automatically.
| Code | Meaning |
|---|---|
| 401 | Missing/invalid key |
| 403 | Revoked key / suspended |
| 404 | Profile not enrolled |
| 422 · LOW_LIGHT | Frame too dark — ask the user for better light |
| 422 · NO_FACE | No detectable face — ask the user to center their face in the oval |
| 200/422 · SPOOF_* | Presentation attack blocked (screen, print, still photo, looped replay). verified:false — ask for a live retry with the guided head turns. No code change needed on your side. |
Two ways, both anonymized (score + optional label only — no images, identities, or end-user IDs):
// A. Per call — add to any verify request:
POST /api/v1/verify-pipeline
{
"endUserId": "user_123",
"frames": ["data:..."],
"contribute": true, // opt in for this call
"truth": "genuine" // "genuine" | "impostor" (optional)
}
// B. Account-wide — one toggle in your dashboard covers
// every keyed verify call (truth tags still per-call):
POST /api/settings/contribute
{ "enabled": true }
// truth is ground truth: was the person the enrolled user?
// Provide it when you know (e.g. an internal test account) to
// contribute to FAR/FRR. Omit it to only contribute to the
// confidence distribution.See the live numbers on the accuracy page.
Every verification returns a confidence score plus a verified decision. Apply your own stricter cutoff on top if your risk policy requires it.