Developer docs · v1

Integrate in 10 minutes

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.

1 · Enroll a user

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" }

2 · Verify with liveness

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.

Voice guidance (optional)

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

Node.js

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 })
});

Python

import requests
r = requests.post(base + '/api/v1/enroll',
 headers={'x-api-key': KEY},
 json={'endUserId': uid, 'frame': data_url})
print(r.json())

PHP

$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]));

Capture SDK — demo-identical widget

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 demo

Liveness SDK (browser)

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

Billing webhooks

Our billing provider notifies POST /api/billing/ipn on payment events. A confirmed payment activates the subscription for 12 months automatically.

Plan: $15/mo billed yearly = $180
POST /api/billing/subscribe —†’ checkout URL

Errors

CodeMeaning
401Missing/invalid key
403Revoked key / suspended
404Profile not enrolled
422 · LOW_LIGHTFrame too dark — ask the user for better light
422 · NO_FACENo 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.

Contribute to the public accuracy benchmark (optional)

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.

Confidence scores

Every verification returns a confidence score plus a verified decision. Apply your own stricter cutoff on top if your risk policy requires it.