Login (Token Auth)

Create a session for a user and get a session token.

Endpoint: POST /auth/login

Headers:

• x-api-key (required) - Your application’s API key
• x-api-secret (required) - Your application’s API secret

Request Body:

{
  "credentials": {
    "username": "john_doe",
    "password": "user_password"
  },
  "hardware_id": "00:1B:44:11:3A:B7"
}

Or with license code:

{
  "credentials": {
    "code": "ABC123XYZ789"
  },
  "hardware_id": "00:1B:44:11:3A:B7"
}

Fields:

• credentials (required) - Either username/password OR license code
• hardware_id (optional) - Required if device authentication is enabled for your app

Response:

{
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Usage:

Store the session token securely and use it in future requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Errors:

• 401 - Invalid credentials
• 401 - Device authentication errors (see Device Authentication)
• 403 - Inactive membership, banned, or temporarily timed out

A timed-out user receives a structured response containing the timeout expiry and optional reason:

{
  "error_code": "TIMED_OUT",
  "message": "User is temporarily timed out",
  "timed_out_until": "2026-09-09T14:30:00+00:00",
  "reason": "Take a short break"
}

See User Timeouts for details.

Notes:

• Session tokens are tied to your application and cannot be used with other apps
• Session tokens include device information when device auth is enabled
• User’s IP address is automatically tracked on login

Login (Legacy Auth)

Legacy authentication doesn’t have a separate login endpoint. Instead, you send user credentials with every request using headers:

• x-api-username + x-api-password, OR
• x-api-license-code
• x-hardware-id (if device auth enabled)

Example Request:

GET /app_context
Headers:
  x-api-key: your_api_key
  x-api-secret: your_api_secret
  x-api-username: john_doe
  x-api-password: user_password
  x-hardware-id: 00:1B:44:11:3A:B7  # only if device auth enabled

This method is simpler but less efficient than token-based authentication since credentials must be validated on every request.

Timed-out credentials receive the same structured 403 response shown above.

Recommendation: Use token-based authentication for better security and performance.