Face-Based Auth for DevOps and Infrastructure

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.

Embedded Widget (optional)

Add facial login to your website in 2 minutes with our ready-to-use widget. Learn more →

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

// 2) Request facial sign-in (sends push notification to user's mobile)
async function requestFacialSignIn(userUid, authToken) {
  const response = await fetch('/api/v1/facial_sign_on/login/push_notification', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${authToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ id: userUid })
  });
  
  const data = await response.json();
  return data.data.verification_token;
}

// 3) Listen for authentication result via ActionCable
function subscribeFacialSignIn(verificationToken) {
  const cable = ActionCable.createConsumer('wss://axiam.io/cable');
  
  cable.subscriptions.create({
    channel: 'FacialSignOnLoginChannel',
    verification_token: verificationToken
  }, {
    received: function(data) {
      if (data.status === 'verified') {
        console.log('User authenticated successfully!');
        window.location.href = '/dashboard';
      } else if (data.status === 'failed') {
        console.log('Authentication failed');
        alert('Facial authentication failed. Please try again.');
      }
    }
  });
}

// Complete workflow example
async function startFacialAuth(userUid) {
  try {
    const authToken = await authenticateApp();
    const verificationToken = await requestFacialSignIn(userUid, authToken);
    subscribeFacialSignIn(verificationToken);
    
    // Show waiting message to user
    document.getElementById('status').innerHTML = 
      'Push notification sent! Please check your mobile device.';
  } catch (error) {
    console.error('Error:', error);
  }
}

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

Embedded Widget

Pre-built JavaScript widget for quick integration. Add facial authentication to your website without handling UI, API calls, or WebSocket connections.

Quick Integration

Add this code to your HTML and you're ready to go:

<div id="axiam-facial-login"></div>
<script src="https://axiam.io/widget/facial-login.js"></script>
<script>
  AxiamFacialLogin.init({
    authToken: 'JWT_FROM_SERVER',
    formAction: '/auth/verified_login'
  });
</script>

Security: Widget v2.0.0 requires server-side JWT authentication for enhanced security.

What You Get

Zero Backend Code: Widget handles all API calls and WebSocket connections
Real-time Updates: Automatic ActionCable subscription for instant verification
Secure by Default: JWT authentication, CSRF protection, rate limiting
Customizable UI: Colors, text, callbacks, and lifecycle events
Mobile Responsive: Works seamlessly on desktop and mobile browsers
Production Ready: Error handling, retry logic, timeout management

How It Works

1

Server Authentication

Your backend gets JWT token from Axiam API

2

Widget Initialization

Pass JWT token to widget config

3

Facial Verification

User enters email, receives push notification

Auto Login

Widget submits verified form to your backend

Complete Widget Integration Guide

Step-by-step integration guide with server-side authentication examples in PHP, Node.js, Ruby, and Python. Learn about configuration options, lifecycle callbacks, security best practices, and troubleshooting.

Widget Quick Start

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.

Facial Sign‑In Documentation