API Documentation
Base URL: https://faceauth.93-127-142-148.sslip.io/api/v1
Overview
FaceAuth API provides passwordless face authentication for your website. Register for an API key, enroll user faces, then verify identities with a single image upload.
Authentication
Include your API key in every protected request using one of:
- Header:
X-API-Key: fa_your_key - Header:
Authorization: Bearer fa_your_key - Body field:
api_key
POST /register
POST/api/v1/register
Public — no API key required
Body (JSON)
{ "email": "dev@company.com", "name": "John Doe" }
Response
{
"success": true,
"api_key": "fa_abc123...",
"user": { "id": 1, "email": "dev@company.com", "name": "John Doe", "plan": "free" }
}
POST /enroll
POST/api/v1/enroll
Headers
X-API-Key: YOUR_API_KEY
Body (multipart/form-data)
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Unique User ID (e.g. 101, Rahim) |
| image | file | Yes | Face photo — send 3 images (image, image1, image2) for best accuracy |
Response
{ "success": true, "face_id": 1, "external_user_id": "user_123", "message": "Face enrolled successfully" }
POST /verify
POST/api/v1/verify
Critical mode: distance ≤ 0.42 + confidence ≥ 85% + identity check required
Body (multipart/form-data)
| Field | Type | Required |
|---|---|---|
| image | file | Yes |
| name | string | Yes — enrolled User ID/Name |
Response
{
"success": true,
"match": true,
"status": "match",
"confidence": 94.2,
"identity": "101",
"message": "Verified as 101",
"user": { "id": 1, "external_user_id": "101", "name": "101" }
}
Match logic: distance ≤ 0.42 · confidence ≥ 85% · must match named identity · 3-sample enroll recommended
POST /match
POST/api/v1/match
Body (multipart/form-data)
| Field | Type | Required |
|---|---|---|
| image1 | file | Yes |
| image2 | file | Yes |
Response
{
"success": true,
"match": true,
"status": "match",
"similarity": 95.2,
"confidence": 95.2,
"distance": 0.38
}
GET /usage/:api_key
GET/api/v1/usage/{api_key}
Response
{
"success": true,
"user": { "plan": "free", "api_key": "fa_..." },
"usage": {
"monthly_calls": 42,
"monthly_limit": 1000,
"total_calls": 150,
"success_rate": 94.5,
"enrolled_faces": 3
},
"daily_usage": [{ "day": "2026-06-24", "calls": 12 }],
"recent_logs": []
}
GET /health
GET/api/v1/health
Public
{ "success": true, "status": "healthy", "models_loaded": true, "uptime": 3600 }
Error Codes
| Code | HTTP | Description |
|---|---|---|
| MISSING_API_KEY | 401 | API key not provided |
| INVALID_API_KEY | 401 | API key not found |
| VALIDATION_ERROR | 400 | Invalid request body |
| MISSING_IMAGE | 400 | No image in request |
| NO_FACE | 422 | No face detected in image |
| NO_ENROLLED_FACES | 404 | No faces enrolled for this key |
| RATE_LIMIT | 429 | Per-minute rate limit exceeded |
| MONTHLY_LIMIT | 429 | Monthly call quota exceeded |
| EMAIL_EXISTS | 409 | Email already registered |
| PROCESSING_ERROR | 500 | Face processing failed |
Rate Limits
| Plan | Per Minute | Per Month |
|---|---|---|
| Free | 100 | 1,000 |
| Pro | 1,000 | 10,000 |
| Enterprise | 10,000 | Unlimited |
Embed Widget
<script src="https://faceauth.93-127-142-148.sslip.io/widget.js" data-api-key="YOUR_API_KEY" data-user-id="USER_ID"></script>
<script>
FaceAuth.onSuccess(function(data) {
console.log('Logged in:', data.user);
});
FaceAuth.onError(function(err) {
console.log('Failed:', err);
});
</script>
Try It — Live API Console
Response will appear here...