Getting Started
Create an application in your dashboard and integrate facial authentication into your web application.
API_KEY
, SECRET_KEY
,
and Redis configuration from your application details page.
// 1) Authenticate your application first async function authenticateApp() { const response = await fetch('/api/v1/facial_sign_on/application_auth', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ api_key: 'your-api-key-here', secret_key: 'your-secret-key-here', domain: 'axiam.io' }) }); const data = await response.json(); return data.data.authenticated_token; }
# 1) Authenticate your application to get access token curl -X POST https://axiam.io/api/v1/facial_sign_on/application_auth \ -H "Content-Type: application/json" \ -d '{ "api_key": "your-api-key-here", "secret_key": "your-secret-key-here", "domain": "your-domain" }' # Response: {"success": true, "data": {"authenticated_token": "jwt_token_here", "expires_in": 2592000}} # 2) Send push notification to user's mobile device for facial authentication curl -X POST https://axiam.io/api/v1/facial_sign_on/login/push_notification \ -H "Authorization: Bearer JWT_TOKEN_FROM_STEP_1" \ -H "Content-Type: application/json" \ -d '{"id": "user_uid_here"}' # Response: {"success": true, "data": {"verification_token": "verification_token_here"}} # 3) User scans face on mobile app # 4) Your web client receives real-time result via ActionCable # 5) Redirect user to dashboard on successful authentication
// Real-time authentication using ActionCable const cable = ActionCable.createConsumer('wss://axiam.io/cable'); // Subscribe to facial sign-on channel const subscription = cable.subscriptions.create({ channel: 'FacialSignOnLoginChannel', verification_token: verificationToken }, { received: function(data) { if (data.status === 'verified') { console.log('User authenticated!', data); // Redirect or update UI window.location.href = '/dashboard'; } } });
Facial Sign‑In API
Web client APIs for application authentication and facial sign-in workflow.
curl -X POST https://axiam.io/api/v1/facial_sign_on/application_auth \ -H "Content-Type: application/json" \ -d '{ "api_key": "your-api-key-here", "secret_key": "your-secret-key-here", "domain": "your-domain" }'
curl -X POST https://axiam.io/api/v1/facial_sign_on/login/push_notification \ -H "Authorization: Bearer JWT_TOKEN_FROM_AUTH" \ -H "Content-Type: application/json" \ -d '{ "id": "user_uid_here" }'
// Subscribe to receive real-time authentication results const cable = ActionCable.createConsumer('wss://axiam.io/cable'); cable.subscriptions.create({ channel: 'FacialSignOnLoginChannel', verification_token: 'token_from_push_notification_response' }, { received: function(data) { if (data.status === 'verified') { // User successfully authenticated via mobile app console.log('Authentication successful:', data); window.location.href = '/dashboard'; } else if (data.status === 'failed') { // Authentication failed console.log('Authentication failed:', data); alert('Facial authentication failed. Please try again.'); } } });
Guides
Set up cross-device authentication where users capture facial images on mobile and authenticate on web browsers using push notifications.
Implement real-time authentication updates using WebSockets for instant login confirmation without page refresh.
Handle iOS HEIC format images with automatic conversion to JPEG using ImageMagick for cross-platform compatibility.
Configure multiple websites/domains under one account with isolated user bases and custom API keys per site.
Integrate with Firebase Cloud Messaging for reliable push notification delivery to iOS and Android devices.
Implement secure verification tokens with automatic expiration and cleanup to prevent replay attacks.
Security & Compliance
API Reference
REST endpoints with JSON responses. Authentication required for protected endpoints.
# For application authentication (no token required) Content-Type: application/json Accept: application/json # For protected endpoints (use JWT from application_auth) Authorization: Bearer JWT_TOKEN_HERE Content-Type: application/json Accept: application/json
/application_auth
for protected endpoints.// Subscribe to real-time updates const cable = ActionCable.createConsumer('wss://axiam.io/cable'); cable.subscriptions.create({ channel: "FacialSignOnLoginChannel", verification_token: "token_from_push_response" }, { received: function(data) { // data.status: 'verified' or 'failed' console.log('Auth result:', data.status); } });
{ "success": true, "data": { "authenticated_token": "jwt_token_here", "expires_in": 2592000 } }
{ "success": false, "message": "Authentication failed", "code": 1001, "http_code": 401 }
HTTP Status Codes
Code | Status | Description |
---|---|---|
200 | OK | Request successful |
400 | Bad Request | Missing or invalid parameters |
401 | Unauthorized | Invalid credentials or expired token |
404 | Not Found | User, device, or resource not found |
500 | Internal Server Error | Server error occurred |
Common Error Codes
Code | HTTP Status | Message | Description |
---|---|---|---|
1001 | 401 | Authentication failed | Invalid API key, secret key, or domain |
1002 | 401 | Domain mismatch | Request domain doesn't match registered domain |
1007 | 404 | Client not found | User ID not found or not associated with site |
1012 | 404 | Device token not found | User hasn't registered mobile device |
Changelog
Updates and improvements to the Facial Sign-In API for web client integration.
- 2025-09-22: Updated API documentation to focus on web client integration workflow with accurate examples.
- 2025-09-22: Enhanced API Reference section with JWT authentication flow and common error codes (1001, 1002, 1007, 1012).
- 2025-09-20: Improved verification token security with automatic 10-minute expiration and cleanup for enhanced security.
- 2025-09-19: Enhanced site registration with automatic domain validation and extraction from URLs.
- 2025-09-11: Added multi-tenant support with site-specific API authentication and ActionCable channel isolation.
- 2025-09-11: Introduced
/api/v1/facial_sign_on/application_auth
endpoint for secure JWT-based authentication. - 2025-08-15: Enhanced ActionCable real-time notifications with verification token-based channel subscriptions.
- 2025-06-11: Initial release of Facial Sign-In API with push notification support and real-time authentication status updates.