Axora - API Documentation

🔍 Overview

The Axora Authentication API provides secure user authentication for your applications. The API uses a structured URL format that includes all necessary authentication parameters in a single request.

🔑 Key Features:

Single-endpoint authentication
Hardware-based device binding
Version-aware licensing
Real-time validation

🏗️ Endpoint Structure

GET

Base Authentication URL

{domain}/app/auth/{endpoint}+{username}+{password}+{version}+{hardware_id}

⚠️ Important: The hardware_id parameter should only be provided if "Restrict login access to a single device per user account" is enabled for your application.

URL Component Breakdown

Component	Description	Example	Required
`{domain}`	Your Axora instance domain	`axora.tanishmehta.com`	Required
`/app/auth/`	Fixed API path	`/app/auth/`	Required
`{endpoint}`	Your application endpoint ID	`aSJpwdxP8n90xbFv1Rs2`	Required
`+`	Parameter separator	`+`	Required

📝 Parameters

Parameter	Type	Description	Required	Example
`endpoint`	String	Unique application identifier from your Axora dashboard	Required	`aSJpwdxP8n90xbFv1Rs2`
`username`	String	User's login username	Required	`tanish`
`password`	String	User's login password	Required	`toomuchpain`
`version`	String	Application version for license validation	Required	`3.7.4`
`hardware_id`	String	Unique device identifier (only if device binding enabled)	Conditional	`L5J3K4H7N8`

💡 Hardware ID Generation: The hardware ID should be a unique identifier for the device. Common methods include:

MAC Address hash
CPU ID + Motherboard serial
Custom device fingerprinting

🔐 Authentication Flow

Standard Authentication (Without Device Binding)

// Standard authentication request
GET /app/auth/{endpoint}+{username}+{password}+{version}

// Example URL construction
const endpoint = "aSJpwdxP8n90xbFv1Rs2";
const username = "tanish";
const password = "toomuchpain";
const version = "3.7.4";

const authUrl = `https://axora.tanishmehta.com/app/auth/${endpoint}+${username}+${password}+${version}`;

Device-Bound Authentication

// Device-bound authentication request
GET /app/auth/{endpoint}+{username}+{password}+{version}+{hardware_id}

// Example URL construction with hardware ID
const endpoint = "aSJpwdxP8n90xbFv1Rs2";
const username = "tanish";
const password = "toomuchpain";
const version = "3.7.4";
const hardwareId = "L5J3K4H7N8";

const authUrl = `https://axora.tanishmehta.com/app/auth/${endpoint}+${username}+${password}+${version}+${hardwareId}`;

💡 Examples

📱 Standard Authentication

https://axora.tanishmehta.com/app/auth/aSJpwdxP8n90xbFv1Rs2+tanish+toomuchpain+3.7.4

Basic authentication without device binding. Suitable for web applications or when device restrictions are not required.

🖥️ Device-Bound Authentication

https://axora.tanishmehta.com/app/auth/aSJpwdxP8n90xbFv1Rs2+tanish+toomuchpain+3.7.4+L5J3K4H7N8

Authentication with hardware ID binding. Ensures the user can only access the application from the registered device.

Implementation Examples

// JavaScript/Node.js Example
async function authenticateUser(endpoint, username, password, version, hardwareId = null) {
    let url = `https://axora.tanishmehta.com/app/auth/${endpoint}+${username}+${password}+${version}`;
    
    if (hardwareId) {
        url += `+${hardwareId}`;
    }
    
    try {
        const response = await fetch(url);
        const data = await response.json();
        
        if (response.ok) {
            console.log('Authentication successful:', data);
            return data;
        } else {
            console.error('Authentication failed:', data);
            throw new Error(data.message || 'Authentication failed');
        }
    } catch (error) {
        console.error('Network error:', error);
        throw error;
    }
}

// Python Example
import requests
import urllib.parse

def authenticate_user(endpoint, username, password, version, hardware_id=None):
    base_url = "https://axora.tanishmehta.com/app/auth"
    
    # URL encode parameters to handle special characters
    params = [
        urllib.parse.quote(endpoint),
        urllib.parse.quote(username),
        urllib.parse.quote(password),
        urllib.parse.quote(version)
    ]
    
    if hardware_id:
        params.append(urllib.parse.quote(hardware_id))
    
    url = f"{base_url}/{'+'.join(params)}"
    
    try:
        response = requests.get(url, timeout=10)
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Authentication failed: {response.status_code}")
            
    except requests.RequestException as e:
        raise Exception(f"Network error: {e}")

🛡️ Security Considerations

🚨 Critical Security Notice: Never expose authentication URLs in client-side code, logs, or version control. Always make requests from your secure backend.

Best Practices

Practice	Description	Implementation
HTTPS Only	Always use HTTPS for authentication requests	Ensure all Axora domains use SSL/TLS encryption
Rate Limiting	Implement client-side rate limiting	Limit authentication attempts to prevent abuse
Input Validation	Validate all parameters before sending	Check for required fields, format validation
Error Handling	Handle authentication errors gracefully	Don't expose internal error details to end users
Session Management	Store tokens securely and implement expiry	Use secure storage, implement token refresh

⚠️ URL Encoding: Always URL-encode parameters that may contain special characters (+, &, =, etc.) to prevent parsing errors.

Hardware ID Security

// Example: Secure Hardware ID Generation
const crypto = require('crypto');
const os = require('os');

function generateHardwareId() {
    // Combine multiple hardware identifiers
    const cpuInfo = os.cpus()[0].model;
    const totalMemory = os.totalmem().toString();
    const hostname = os.hostname();
    
    // Create a hash of combined hardware data
    const hardwareString = cpuInfo + totalMemory + hostname;
    const hardwareId = crypto
        .createHash('sha256')
        .update(hardwareString)
        .digest('hex')
        .substring(0, 10); // First 10 characters
    
    return hardwareId.toUpperCase();
}

// Usage
const hardwareId = generateHardwareId();
console.log('Hardware ID:', hardwareId); // Example: L5J3K4H7N8

Direct Integration Examples

Note: Axora doesn't currently provide official SDKs. Below are examples of direct API integration in various programming languages.

C# / .NET Example

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class AxoraAuth
{
    private readonly HttpClient _httpClient;
    private readonly string _domain;

    public AxoraAuth(string domain)
    {
        _httpClient = new HttpClient();
        _domain = domain;
    }

    public async Task<AuthResponse> AuthenticateAsync(string endpoint, string username, 
        string password, string version, string hardwareId = null)
    {
        var url = $"https://{_domain}/app/auth/{endpoint}+{username}+{password}+{version}";
        
        if (!string.IsNullOrEmpty(hardwareId))
        {
            url += $"+{hardwareId}";
        }

        var response = await _httpClient.GetAsync(url);
        var json = await response.Content.ReadAsStringAsync();
        
        return JsonConvert.DeserializeObject<AuthResponse>(json);
    }
}

public class AuthResponse
{
    public bool Authenticated { get; set; }
    public string Message { get; set; }
    public string AppId { get; set; }
    public string AppName { get; set; }
    public string Endpoint { get; set; }
}

Java Example

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;

public class AxoraAuth {
    private final HttpClient httpClient;
    private final String domain;
    private final ObjectMapper mapper;

    public AxoraAuth(String domain) {
        this.httpClient = HttpClient.newHttpClient();
        this.domain = domain;
        this.mapper = new ObjectMapper();
    }

    public AuthResponse authenticate(String endpoint, String username, 
            String password, String version, String hardwareId) throws Exception {
        
        String url = String.format("https://%s/app/auth/%s+%s+%s+%s", 
            domain, endpoint, username, password, version);
        
        if (hardwareId != null && !hardwareId.isEmpty()) {
            url += "+" + hardwareId;
        }

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .GET()
            .build();

        HttpResponse<String> response = httpClient.send(request, 
            HttpResponse.BodyHandlers.ofString());

        return mapper.readValue(response.body(), AuthResponse.class);
    }
}

PHP Example

<?php

class AxoraAuth {
    private $domain;

    public function __construct($domain) {
        $this->domain = $domain;
    }

    public function authenticate($endpoint, $username, $password, $version, $hardwareId = null) {
        $url = "https://{$this->domain}/app/auth/{$endpoint}+{$username}+{$password}+{$version}";
        
        if ($hardwareId !== null) {
            $url .= "+{$hardwareId}";
        }

        $response = file_get_contents($url);
        
        if ($response === false) {
            throw new Exception('Failed to make request');
        }

        $data = json_decode($response, true);
        
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new Exception('Invalid JSON response');
        }

        return $data;
    }
}

// Usage
$auth = new AxoraAuth('axora.tanishmehta.com');

try {
    $result = $auth->authenticate(
        'aSJpwdxP8n90xbFv1Rs2', 
        'tanish', 
        'toomuchpain', 
        '3.7.4'
    );
    
    if ($result['authenticated']) {
        echo "Authentication successful!";
    } else {
        echo "Authentication failed: " . $result['message'];
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

?>

Support & Troubleshooting

Common Authentication Issues

Issue: "Credential disabled or invalid"
This means either the username/password combination doesn't exist in your app credentials, or the credential has been disabled.

Solution: Check your dashboard to verify the credential exists and is active.

Issue: "App disabled or not found"
The app endpoint doesn't exist or has been disabled.

Solution: Verify your app endpoint ID in the dashboard and ensure the app is enabled.

Issue: "Update required. Current version: X.X.X"
Version enforcement is enabled and the client version doesn't match the required version.

Solution: Either update your client to the required version or disable version enforcement in the dashboard.

Issue: "This user is logged into another device"
Hardware lock is enabled and the user is trying to login from a different device.

Solution: Reset the hardware ID for this credential in the dashboard, or disable hardware lock.

Troubleshooting Tips:

URL Encoding: Special characters in passwords must be URL-encoded
Parameter Order: Ensure parameters are in the correct order: endpoint+username+password+version+hardware_id
Hardware ID Consistency: The same device should always generate the same hardware ID
Case Sensitivity: All parameters are case-sensitive

Testing Your Integration

// Test authentication with curl
curl -L "https://axora.tanishmehta.com/app/auth/YOUR_ENDPOINT+YOUR_USERNAME+YOUR_PASSWORD+1.0.0"

// Expected successful response:
{
  "authenticated": true,
  "app_id": "your_app_id",
  "app_name": "Your App Name",
  "endpoint": "your_endpoint",
  "message": "Authentication successful"
}

Authentication API

📋 Table of Contents