API Documentation

Complete guide to integrating Lockence authentication into your applications. Works with Python, C++, C#, and any language that supports HTTP requests.

Quick Start
Get up and running in 5 minutes
  1. Create an account and log in to your dashboard
  2. Create a new application and copy your API key
  3. Generate a license key for testing
  4. Use the code examples below to integrate into your application
Base URL
https://your-domain.com/api/v1
Authentication
All API requests require your application API key

Include your API key in the request body for all endpoints. You can find your API key in the dashboard after creating an application.

{ "api_key": "your_api_key_here", ... }
Initialize License
POST /api/v1/init

Validates a license key and creates an authenticated session. This is the first endpoint you call when a user starts your application.

Request Body

{ "api_key": "string", // Your application API key "license_key": "string", // User's license key "hwid": "string" // Hardware ID (unique device identifier) }

Success Response (200)

{ "success": true, "message": "Authentication successful", "session_token": "uuid", "expires_at": "2025-01-18T12:00:00Z", "username": "john_doe", "metadata": {} }

Error Response (403/404)

{ "success": false, "message": "Invalid license key" | "License expired" | "HWID mismatch" }
import requests
import hashlib
import platform

def get_hwid():
    """Generate hardware ID from machine info"""
    return hashlib.sha256(
        platform.node().encode()
    ).hexdigest()

def initialize_license(api_key, license_key):
    """Initialize and validate license"""
    response = requests.post(
        "https://your-domain.com/api/v1/init",
        json={
            "api_key": api_key,
            "license_key": license_key,
            "hwid": get_hwid()
        }
    )
    
    data = response.json()
    if data["success"]:
        return data["session_token"]
    else:
        raise Exception(data["message"])

# Usage
try:
    session = initialize_license(
        "your_api_key",
        "XXXXX-XXXXX-XXXXX-XXXXX"
    )
    print(f"Authenticated! Session: {session}")
except Exception as e:
    print(f"Authentication failed: {e}")
Validate Session
POST /api/v1/validate

Checks if a session is still valid. Call this periodically to ensure the user is still authenticated.

Request Body

{ "api_key": "string", "session_token": "string" }

Success Response (200)

{ "success": true, "message": "Session is valid", "username": "john_doe", "metadata": {} }
def validate_session(api_key, session_token):
    """Validate an active session"""
    response = requests.post(
        "https://your-domain.com/api/v1/validate",
        json={
            "api_key": api_key,
            "session_token": session_token
        }
    )
    
    data = response.json()
    return data["success"]

# Usage
if validate_session("your_api_key", session_token):
    print("Session is valid")
else:
    print("Session expired or invalid")
Heartbeat
POST /api/v1/heartbeat

Updates the last activity timestamp for a session. Call this every few minutes to keep the session alive and track user activity.

Request Body

{ "api_key": "string", "session_token": "string" }

Example (Python)

import time
import threading

def heartbeat_loop(api_key, session_token):
    """Send heartbeat every 5 minutes"""
    while True:
        try:
            requests.post(
                "https://your-domain.com/api/v1/heartbeat",
                json={
                    "api_key": api_key,
                    "session_token": session_token
                }
            )
        except:
            pass
        time.sleep(300)  # 5 minutes

# Start heartbeat in background thread
thread = threading.Thread(
    target=heartbeat_loop,
    args=(api_key, session_token),
    daemon=True
)
thread.start()
Logout
POST /api/v1/logout

Terminates an active session. Call this when the user closes your application or logs out.

Request Body

{ "api_key": "string", "session_token": "string" }

Example (Python)

def logout(api_key, session_token):
    """Terminate session"""
    response = requests.post(
        "https://your-domain.com/api/v1/logout",
        json={
            "api_key": api_key,
            "session_token": session_token
        }
    )
    return response.json()["success"]
Best Practices
  • Store the session token securely and never expose it to end users
  • Implement heartbeat calls every 5-10 minutes to track active usage
  • Always call logout when your application closes to clean up sessions
  • Handle network errors gracefully and retry failed requests
  • Cache the HWID to avoid regenerating it on every request
  • Validate sessions periodically to detect expired or revoked licenses
  • Never hardcode API keys - load them from environment variables or config files
Error Codes
401 Unauthorized

Invalid API key

403 Forbidden

License expired, disabled, or HWID mismatch

404 Not Found

License key or session not found

500 Internal Server Error

Server error - contact support

Need Help?

If you have questions or need assistance integrating Lockence, we're here to help!