Authentication

KULVEX uses JWT (JSON Web Tokens) for API and Socket.IO authentication.

Login

curl -X POST http://localhost:9100/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

Response:

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "user": {
    "id": "...",
    "username": "admin",
    "role": "admin"
  }
}

Using Tokens

REST API

curl http://localhost:9100/api/ai/status \
  -H "Authorization: Bearer YOUR_TOKEN"

Socket.IO

const socket = io("http://localhost:9100", {
  auth: { token: "YOUR_TOKEN" },
});

Token Lifecycle

• Tokens are long-lived (no automatic expiration for permanent sessions)
• Mobile app sessions persist until the device is powered off
• Refresh via POST /api/auth/refresh with a valid token

Roles

First User

The first user to register becomes the admin. Subsequent registrations require admin approval or an invite link.

Public Endpoints

These endpoints do not require authentication:

• GET /health
• POST /api/auth/login
• POST /api/auth/register (first user only, or with invite)
• GET /install (license server only)