Skip to content
Last updated

🔐 iVALT Authentication APIs

Overview

The iVALT Authentication APIs let you verify user identities in real time using biometrics, device trust, and contextual rules.
Integrate these endpoints into your applications to provide seamless, 1-Click authentication without passwords or shared secrets.

🚀 Quick Start: Authenticate a User in 3 Steps

Step 1: Generate Auth Token

Obtain an authentication token using your client credentials to authenticate API requests.

Endpoint: POST /generate-auth-token

Step 2: Verify User

Send the user's country code and mobile number to initiate authentication and trigger a push notification.

Endpoint: POST /verify-user

Step 3: Submit Biometric & Geo-Fence Results

After the user completes biometric verification on their device, submit the authentication results.

Endpoint: POST /biometric-geo-fence-auth-results

💻 Code Example: Complete Authentication Flow

Step 1: Generate Authentication Token

// JavaScript/Node.js Example
const axios = require('axios');

const generateAuthToken = async (apiKey) => {
  const response = await axios.post(
    'https://api.ivalt.com/admin/public/api/generate-auth-token',
    {
      // Add required parameters based on your API spec
    },
    {
      headers: {
        'x-api-key': apiKey,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
};
# Python Example
import requests

def generate_auth_token(api_key):
    headers = {
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    }
    
    response = requests.post(
        'https://api.ivalt.com/admin/public/api/generate-auth-token',
        headers=headers,
        json={}
    )
    
    return response.json()
# cURL Example
curl -X POST https://api.ivalt.com/admin/public/api/generate-auth-token \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Step 2: Verify User & Initiate Authentication

// JavaScript/Node.js Example
const verifyUser = async (apiKey, countryCode, mobile) => {
  const response = await axios.post(
    'https://api.ivalt.com/admin/public/api/verify-user',
    {
      country_code: countryCode,
      mobile: mobile
    },
    {
      headers: {
        'x-api-key': apiKey,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
};

// Usage
const result = await verifyUser('YOUR_API_KEY', '+91', '6283974746');
console.log('Status:', result.status);
console.log('Message:', result.message);
# Python Example
def verify_user(api_key, country_code, mobile):
    headers = {
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    }
    
    response = requests.post(
        'https://api.ivalt.com/admin/public/api/verify-user',
        headers=headers,
        json={
            'country_code': country_code,
            'mobile': mobile
        }
    )
    
    return response.json()

# Usage
result = verify_user('YOUR_API_KEY', '+91', '6283974746')
print(f"Status: {result['status']}")
print(f"Message: {result['message']}")
# cURL Example
curl -X POST https://api.ivalt.com/admin/public/api/verify-user \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "+91",
    "mobile": "6283974746"
  }'

Step 3: Submit Biometric & Geo-Fence Results

// JavaScript/Node.js Example
const submitAuthResults = async (apiKey, authData) => {
  const response = await axios.post(
    'https://api.ivalt.com/admin/public/api/biometric-geo-fence-auth-results',
    {
      user_id: authData.userId,
      biometric_result: authData.biometricResult,
      geo_fence_result: authData.geoFenceResult,
      device_info: authData.deviceInfo,
      timestamp: authData.timestamp
    },
    {
      headers: {
        'x-api-key': apiKey,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
};

// Usage
const authResult = await submitAuthResults('YOUR_API_KEY', {
  userId: 'user_123',
  biometricResult: 'PASS',
  geoFenceResult: 'PASS',
  deviceInfo: {
    device_id: 'device_12345',
    platform: 'iOS'
  },
  timestamp: new Date().toISOString()
});

if (authResult.status === 'success') {
  console.log('Authentication successful!');
  console.log('Message:', authResult.message);
} else {
  console.log('Authentication failed:', authResult.message);
}
# Python Example
from datetime import datetime

def submit_auth_results(api_key, auth_data):
    headers = {
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    }
    
    response = requests.post(
        'https://api.ivalt.com/admin/public/api/biometric-geo-fence-auth-results',
        headers=headers,
        json={
            'user_id': auth_data['user_id'],
            'biometric_result': auth_data['biometric_result'],
            'geo_fence_result': auth_data['geo_fence_result'],
            'device_info': auth_data['device_info'],
            'timestamp': auth_data['timestamp']
        }
    )
    
    return response.json()

# Usage
auth_result = submit_auth_results('YOUR_API_KEY', {
    'user_id': 'user_123',
    'biometric_result': 'PASS',
    'geo_fence_result': 'PASS',
    'device_info': {
        'device_id': 'device_12345',
        'platform': 'iOS'
    },
    'timestamp': datetime.now().isoformat()
})

if auth_result['status'] == 'success':
    print('Authentication successful!')
    print(f"Message: {auth_result['message']}")
else:
    print(f"Authentication failed: {auth_result['message']}")
# cURL Example
curl -X POST https://api.ivalt.com/admin/public/api/biometric-geo-fence-auth-results \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "biometric_result": "PASS",
    "geo_fence_result": "PASS",
    "device_info": {
      "device_id": "device_12345",
      "platform": "iOS"
    },
    "timestamp": "2025-11-10T22:00:00Z"
  }'

⚡ Key Capabilities

FeatureDescription
Token GenerationSecurely obtain authentication tokens using client credentials.
User VerificationValidate a user's phone number and device identity before authentication.
Biometric + Geo-Fence ResultsSubmit biometric and location data for verification.
Rule EvaluationAutomatically applies your configured rules (geo-fence, time window, IP, device, etc.) to every login attempt.
Unified ResponseReturns clear pass/fail results and rule evaluation details for your app to act on.

🔄 Authentication Flow Overview

The iValt authentication process follows a simple, secure flow:

  1. Your app requests authentication by calling the verify-user endpoint with the user's phone number
  2. iValt sends a push notification to the user's registered mobile device
  3. User completes biometric verification (face/fingerprint) on their device
  4. iValt mobile app captures biometric result + contextual data (location, device info, timestamp)
  5. Your app submits the biometric result to iValt APIs
  6. iValt Rules Engine evaluates all configured security policies (geo-fence, time windows, IP restrictions, device trust, etc.)
  7. iValt returns authentication decision (PASS/FAIL) with detailed factor evaluation
Security Note

Each authentication request is evaluated against your organization's configured security rules. The Rules Engine checks multiple factors including biometrics, location, device trust, time windows, and IP restrictions to ensure secure access.

📚 Next Steps

  • Explore the full API reference in the sidebar
  • Configure authentication rules in the Admin Portal APIs
  • Test endpoints using the Try It console on each API page
  • Review response codes and error handling in the API documentation