IntelSight/Hetzner-Backup
3
0
Fork 0
Code Issues Pull-Requests Actions Pakete Projekte Releases Wiki Aktivität
Dateien
1146406393419438c4170323dd3f3bdabee359a3
Hetzner-Backup/API_REFERENCE.md
UserIsMH 889a7b4ebe Documentation Update
2025-06-22 12:47:59 +02:00

14 KiB
Originalformat Blame Verlauf

V2-Docker API Reference

Authentication

API Key Authentication

All License Server API endpoints require authentication using an API key. The API key must be included in the request headers.

Header Format:

X-API-Key: AF-2025-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

API Key Management:

  • API keys can be managed through the Admin Panel under Administration → API Keys
  • Keys follow the format: AF-YYYY-[32 random characters]
  • Only one system API key is active at a time
  • Regenerating the key will immediately invalidate the old key

Error Response (401 Unauthorized):

{
  "error": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "status": 401
}

License Server API

Public Endpoints

GET /

Root endpoint - Service status.

Response:

{
  "status": "ok",
  "service": "V2 License Server",
  "timestamp": "2025-06-19T10:30:00Z"
}

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "timestamp": "2025-06-19T10:30:00Z"
}

GET /metrics

Prometheus metrics endpoint.

Response: Prometheus metrics in CONTENT_TYPE_LATEST format.

License API Endpoints

All license endpoints require API key authentication via X-API-Key header.

POST /api/license/activate

Activate a license on a new system.

Headers:

X-API-Key: AF-2025-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

Request:

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "hardware_hash": "unique-hardware-identifier",
  "machine_name": "DESKTOP-ABC123",
  "app_version": "1.0.0"
}

Response:

{
  "message": "License activated successfully",
  "activation": {
    "id": 123,
    "license_key": "XXXX-XXXX-XXXX-XXXX",
    "hardware_hash": "unique-hardware-identifier",
    "machine_name": "DESKTOP-ABC123",
    "activated_at": "2025-06-19T10:30:00Z",
    "last_heartbeat": "2025-06-19T10:30:00Z",
    "is_active": true
  }
}

POST /api/license/verify

Verify an active license.

Headers:

X-API-Key: AF-2025-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

Request:

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "hardware_hash": "unique-hardware-identifier",
  "app_version": "1.0.0"
}

Response:

{
  "valid": true,
  "message": "License is valid",
  "license": {
    "key": "XXXX-XXXX-XXXX-XXXX",
    "valid_until": "2026-01-01",
    "max_users": 10
  },
  "update_available": false,
  "latest_version": "1.0.0"
}

GET /api/license/info/{license_key}

Get license information.

Headers:

X-API-Key: your-api-key

Response:

{
  "license": {
    "id": 123,
    "key": "XXXX-XXXX-XXXX-XXXX",
    "customer_name": "ACME Corp",
    "type": "perpetual",
    "valid_from": "2025-01-01",
    "valid_until": "2026-01-01",
    "max_activations": 5,
    "max_users": 10,
    "is_active": true
  },
  "activations": [
    {
      "id": 456,
      "hardware_hash": "unique-hardware-identifier",
      "machine_name": "DESKTOP-ABC123",
      "activated_at": "2025-06-19T10:00:00Z",
      "last_heartbeat": "2025-06-19T14:30:00Z",
      "is_active": true
    }
  ]
}

Session Management API Endpoints

POST /api/license/session/start

Start a new session for a license.

Headers:

X-API-Key: AF-2025-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

Request:

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "machine_id": "DESKTOP-ABC123",
  "hardware_hash": "unique-hardware-identifier",
  "version": "1.0.0"
}

Response:

  • 200 OK: Returns session_token and optional update info
  • 409 Conflict: "Es ist nur eine Sitzung erlaubt..." (single session enforcement)

POST /api/license/session/heartbeat

Keep session alive with heartbeat.

Headers:

X-API-Key: AF-2025-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

Request:

{
  "session_token": "550e8400-e29b-41d4-a716-446655440000",
  "license_key": "XXXX-XXXX-XXXX-XXXX"
}

Response: 200 OK with last_heartbeat timestamp

POST /api/license/session/end

End an active session.

Headers:

X-API-Key: AF-2025-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

Request:

{
  "session_token": "550e8400-e29b-41d4-a716-446655440000"
}

Response: 200 OK with session duration and end reason

Version API Endpoints

POST /api/version/check

Check for available updates.

Headers:

X-API-Key: your-api-key

Request:

{
  "current_version": "1.0.0",
  "license_key": "XXXX-XXXX-XXXX-XXXX"
}

Response: Update availability status with version info

GET /api/version/latest

Get latest version information.

Headers:

X-API-Key: your-api-key

Response: Latest version information

Admin Panel API

Customer API Endpoints

GET /api/customers

Search customers for Select2 dropdown.

Query Parameters:

  • q: Search query
  • page: Page number (default: 1)

Response:

{
  "results": [
    {
      "id": 123,
      "text": "ACME Corp - admin@acme.com"
    }
  ],
  "pagination": {
    "more": false
  }
}
  • GET /api/customer/{id}/licenses - List customer's licenses
  • GET /api/customer/{id}/quick-stats - License and activation counts

License Management API

  • POST /api/license/{id}/toggle - Toggle active status
  • POST /api/licenses/bulk-activate - Activate multiple (license_ids array)
  • POST /api/licenses/bulk-deactivate - Deactivate multiple
  • POST /api/licenses/bulk-delete - Delete multiple
  • POST /api/license/{id}/quick-edit - Update validity/limits
  • GET /api/license/{id}/devices - List registered devices

POST /api/license/{license_id}/quick-edit

Quick edit license properties.

Request:

{
  "valid_until": "2027-01-01",
  "max_activations": 10,
  "max_users": 50
}

Response:

{
  "success": true,
  "message": "License updated successfully"
}

POST /api/generate-license-key

Generate a new license key.

Response:

{
  "license_key": "NEW1-NEW2-NEW3-NEW4"
}

Device Management API

GET /api/license/{license_id}/devices

Get devices for a license.

Response:

{
  "devices": [
    {
      "id": 123,
      "hardware_hash": "unique-hardware-identifier",
      "machine_name": "DESKTOP-ABC123",
      "activated_at": "2025-01-01T10:00:00Z",
      "last_heartbeat": "2025-06-19T14:30:00Z",
      "is_active": true,
      "app_version": "1.0.0"
    }
  ]
}

POST /api/license/{license_id}/register-device

Register a new device.

Request:

{
  "hardware_hash": "unique-hardware-identifier",
  "machine_name": "DESKTOP-XYZ789",
  "app_version": "1.0.0"
}

Response:

{
  "success": true,
  "device_id": 456,
  "message": "Device registered successfully"
}

POST /api/license/{license_id}/deactivate-device/{device_id}

Deactivate a device.

Response:

{
  "success": true,
  "message": "Device deactivated successfully"
}

Resource Management API

GET /api/license/{license_id}/resources

Get resources for a license.

Response:

{
  "resources": [
    {
      "id": 789,
      "type": "server",
      "identifier": "SRV-001",
      "status": "allocated",
      "allocated_at": "2025-06-01T10:00:00Z"
    }
  ]
}

POST /api/resources/allocate

Allocate resources to a license.

Request:

{
  "license_id": 123,
  "resource_ids": [789, 790]
}

Response:

{
  "success": true,
  "allocated": 2,
  "message": "2 resources allocated successfully"
}

GET /api/resources/check-availability

Check resource availability.

Query Parameters:

  • type: Resource type
  • count: Number of resources needed

Response:

{
  "available": true,
  "count": 5,
  "resources": [
    {
      "id": 791,
      "type": "server",
      "identifier": "SRV-002"
    }
  ]
}

GET /api/resources/stats

Get resource statistics.

Response:

{
  "total": 100,
  "allocated": 75,
  "available": 25,
  "by_type": {
    "server": {
      "total": 50,
      "allocated": 40,
      "available": 10
    },
    "workstation": {
      "total": 50,
      "allocated": 35,
      "available": 15
    }
  }
}

Search API

GET /api/global-search

Global search across all entities.

Query Parameters:

  • q: Search query
  • type: Entity type filter (customer, license, device)
  • limit: Maximum results (default: 20)

Response:

{
  "results": [
    {
      "type": "customer",
      "id": 123,
      "title": "ACME Corp",
      "subtitle": "admin@acme.com",
      "url": "/customer/edit/123"
    },
    {
      "type": "license",
      "id": 456,
      "title": "XXXX-XXXX-XXXX-XXXX",
      "subtitle": "ACME Corp - Active",
      "url": "/license/edit/456"
    }
  ],
  "total": 15
}

Lead Management API

GET /leads/api/institutions

Get all institutions with pagination.

Query Parameters:

  • page: Page number (default: 1)
  • per_page: Items per page (default: 20)
  • search: Search query

Response:

{
  "institutions": [
    {
      "id": 1,
      "name": "Tech University",
      "contact_count": 5,
      "created_at": "2025-06-19T10:00:00Z"
    }
  ],
  "total": 100,
  "page": 1,
  "per_page": 20
}

POST /leads/api/institutions

Create a new institution.

Request:

{
  "name": "New University"
}

Response:

{
  "id": 101,
  "name": "New University",
  "created_at": "2025-06-19T15:00:00Z"
}

GET /leads/api/contacts/{contact_id}

Get contact details.

Response:

{
  "id": 1,
  "first_name": "John",
  "last_name": "Doe",
  "position": "IT Manager",
  "institution_id": 1,
  "details": [
    {
      "id": 1,
      "type": "email",
      "value": "john.doe@example.com",
      "label": "Work"
    },
    {
      "id": 2,
      "type": "phone",
      "value": "+49 123 456789",
      "label": "Mobile"
    }
  ],
  "notes": [
    {
      "id": 1,
      "content": "Initial contact",
      "version": 1,
      "created_at": "2025-06-19T10:00:00Z",
      "created_by": "admin"
    }
  ]
}

POST /leads/api/contacts/{contact_id}/details

Add contact detail (phone/email).

Request:

{
  "type": "email",
  "value": "secondary@example.com",
  "label": "Secondary"
}

Response:

{
  "id": 3,
  "type": "email",
  "value": "secondary@example.com",
  "label": "Secondary"
}

Resource Management API

GET /api/resources/availability

Get resource availability for license allocation.

Response:

{
  "domains": {
    "available": 150,
    "total": 200,
    "status": "ok"
  },
  "ipv4": {
    "available": 45,
    "total": 100,
    "status": "low"
  },
  "phone_numbers": {
    "available": 5,
    "total": 50,
    "status": "critical"
  }
}

POST /api/resources/allocate

Allocate resources to a license.

Request:

{
  "license_id": 123,
  "resource_type": "domain",
  "resource_ids": [45, 46, 47]
}

Response:

{
  "success": true,
  "allocated": 3,
  "message": "3 resources allocated successfully"
}

Monitoring API

GET /api/monitoring/dashboard

Get monitoring dashboard data.

Response:

{
  "metrics": {
    "total_licenses": 1500,
    "active_licenses": 1200,
    "total_customers": 250,
    "active_sessions": 890
  },
  "alerts": [
    {
      "level": "warning",
      "message": "High CPU usage on license server",
      "timestamp": "2025-06-19T14:00:00Z"
    }
  ]
}

GET /api/sessions/active-count

Get count of active sessions.

Response:

{
  "count": 42
}

Monitoring API

GET /api/monitoring/live-stats

Get live statistics for monitoring.

Response:

{
  "timestamp": "2025-06-19T14:30:00Z",
  "metrics": {
    "active_licenses": 850,
    "total_activations": 2500,
    "active_sessions": 1200,
    "heartbeats_per_minute": 450
  },
  "alerts": [
    {
      "type": "warning",
      "message": "High CPU usage detected",
      "timestamp": "2025-06-19T14:25:00Z"
    }
  ]
}

GET /api/monitoring/anomaly-stats

Get anomaly statistics.

Response:

{
  "total_anomalies": 15,
  "unresolved": 3,
  "by_type": {
    "unusual_activation_pattern": 5,
    "excessive_heartbeats": 3,
    "license_hopping": 7
  }
}

GET /api/admin/license/auth-token

Get JWT token for analytics access.

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-06-19T15:30:00Z"
}

Lead Management API

GET /leads/api/stats

Get lead statistics.

Response:

{
  "total_institutions": 150,
  "total_contacts": 450,
  "recent_activities": 25,
  "conversion_rate": 12.5,
  "by_type": {
    "university": 50,
    "company": 75,
    "government": 25
  }
}

Lead Routes (HTML Pages)

  • GET /leads/ - Lead overview page
  • GET /leads/create - Create lead form
  • POST /leads/create - Save new lead
  • GET /leads/edit/{lead_id} - Edit lead form
  • POST /leads/update/{lead_id} - Update lead
  • POST /leads/delete/{lead_id} - Delete lead
  • GET /leads/export - Export leads
  • POST /leads/import - Import leads

Common Response Codes

  • 200 OK: Successful request
  • 201 Created: Resource created
  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict (e.g., duplicate)
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Rate Limiting

  • API endpoints: 100 requests/minute
  • Login attempts: 5 per minute
  • Configurable via Admin Panel

Error Response Format

All errors return JSON with error, code, and status fields.

Client Integration

Example request with required headers:

curl -X POST http://localhost/api/license/activate \
  -H "X-API-Key: AF-2025-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "XXXX-XXXX-XXXX-XXXX",
    "hardware_hash": "unique-hardware-id",
    "machine_name": "DESKTOP-123",
    "app_version": "1.0.0"
  }'

Testing

Test Credentials

  • Admin Users:
    • Username: rac00n / Password: 1248163264
    • Username: w@rh@mm3r / Password: Warhammer123!
  • API Key: Generated in Admin Panel under "Lizenzserver Administration"

Test Endpoints

  • Admin Panel: http://localhost:80
  • License Server API: http://localhost:80/api
  • Monitoring: See OPERATIONS_GUIDE.md
In neuem Issue referenzieren Git Blame ansehen Permalink kopieren