# 🔐 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
// 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
# 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
# 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
// 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
# 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
# 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
// 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
# 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
# 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

| Feature | Description |
|  --- | --- |
| **Token Generation** | Securely obtain authentication tokens using client credentials. |
| **User Verification** | Validate a user's phone number and device identity before authentication. |
| **Biometric + Geo-Fence Results** | Submit biometric and location data for verification. |
| **Rule Evaluation** | Automatically applies your configured rules (geo-fence, time window, IP, device, etc.) to every login attempt. |
| **Unified Response** | Returns 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](/products/admin-portal)
- Test endpoints using the **Try It** console on each API page
- Review response codes and error handling in the API documentation