Facial Sign‑In Documentation

Integrate Axiam to replace passwords and fragile OTPs with live facial verification—faster, safer, and traceable.

Getting Started

Create an application in your dashboard and integrate facial authentication into your web application.

Create Application
Login to your dashboard, go to Apps section, and click "Add New App" to create your application.
Get Credentials
Copy your API_KEY, SECRET_KEY, and Redis configuration from your application details page.
Install Mobile App
Download Axiam mobile app for facial capture and device registration. Scan QR code to link with your account.
// 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.

POST /api/v1/facial_sign_on/application_auth
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"
}'
Purpose: Authenticate your web application to get JWT access token for subsequent API calls.
POST /api/v1/facial_sign_on/login/push_notification
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"
}'
Purpose: Send push notification to user's mobile device to trigger facial authentication process.
ActionCable WebSocket Channel
// 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.');
    }
  }
});
Purpose: Receive real-time updates when user completes facial authentication on their mobile device.

Guides

Mobile + Web Integration

Set up cross-device authentication where users capture facial images on mobile and authenticate on web browsers using push notifications.

ActionCable Real-time Authentication

Implement real-time authentication updates using WebSockets for instant login confirmation without page refresh.

HEIC Image Processing

Handle iOS HEIC format images with automatic conversion to JPEG using ImageMagick for cross-platform compatibility.

Multi-tenant Site Management

Configure multiple websites/domains under one account with isolated user bases and custom API keys per site.

Firebase Push Notifications

Integrate with Firebase Cloud Messaging for reliable push notification delivery to iOS and Android devices.

Token Security & Expiration

Implement secure verification tokens with automatic expiration and cleanup to prevent replay attacks.


Security & Compliance

API Security
Bearer token authentication, rate limiting, CORS protection, and automatic token expiration (10 minutes) for verification tokens.
Image Processing
Secure image upload with format validation, size limits (10MB max), automatic HEIC conversion, and Paperclip attachment security.
Data Protection
MySQL database with encrypted connections, automatic cleanup of expired tokens, and secure device token storage.
Monitoring
Comprehensive request logging, failed attempt tracking, facial sign-on status management, and automated cleanup jobs.

API Reference

REST endpoints with JSON responses. Authentication required for protected endpoints.

Authentication Headers
# 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
Use JWT token from /application_auth for protected endpoints.
ActionCable Channel
// 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);
  }
});
WebSocket channel for real-time authentication updates.
Success Response Format
{
  "success": true,
  "data": {
    "authenticated_token": "jwt_token_here",
    "expires_in": 2592000
  }
}
Standard success response with relevant data payload.
Error Response Format
{
  "success": false,
  "message": "Authentication failed",
  "code": 1001,
  "http_code": 401
}
Standard error response with custom error codes.

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.