IntelSight/v2-Docker
3
0
Fork 0
Code Issues Pull-Requests Actions Pakete Projekte Releases Wiki Aktivität
Files
main
v2-Docker/API_REFERENCE.md
Claude Project Manager 0d7d888502 Initial commit
2025-07-05 17:51:16 +02:00

13 KiB
Originalformat Permalink 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 "Lizenzserver Administration" → "System-API-Key generieren"
  • 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
  • The initial API key is automatically generated on first startup
  • To retrieve the initial API key from database: SELECT api_key FROM system_api_key WHERE id = 1;

Error Response (401 Unauthorized):

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

License Server API

Base URL: https://api-software-undso.intelsight.de

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: AF-2025-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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

Note: Session endpoints require that the client application is configured in the client_configs table. The default client "Account Forger" is pre-configured.

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: AF-2025-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request:

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

Response:

{
  "update_available": true,
  "latest_version": "1.1.0",
  "download_url": "https://example.com/download/v1.1.0",
  "release_notes": "Bug fixes and performance improvements"
}

GET /api/version/latest

Get latest version information.

Headers:

X-API-Key: AF-2025-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Response:

{
  "version": "1.1.0",
  "release_date": "2025-06-20",
  "download_url": "https://example.com/download/v1.1.0",
  "release_notes": "Bug fixes and performance improvements"
}

Admin Panel API

Base URL: https://admin-panel-undso.intelsight.de

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
  }
}

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"
    }
  ]
}

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

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"
}

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 https://api-software-undso.intelsight.de/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"

Getting the Initial API Key

If you need to retrieve the API key directly from the database:

docker exec -it v2_postgres psql -U postgres -d v2_db -c "SELECT api_key FROM system_api_key WHERE id = 1;"

Test Endpoints

  • Admin Panel: https://admin-panel-undso.intelsight.de/
  • License Server API: https://api-software-undso.intelsight.de/