Login API

Authenticate users and obtain JWT tokens for API access.

Login Endpoint

Authenticates a user by username and password, returning a JWT token for subsequent API requests.

Request

POST /api/login

Request Body

{
  "username": "string",
  "password": "string",
  "api_key": ""
}

Parameters

Parameter	Type	Required	Description
username	string	Yes	User's username
password	string	Yes	User's password
api_key	string	Yes	Must be sent as empty string

Example Request

curl -X POST "http://your-server-ip:port/api/login" \
     -H "Content-Type: application/json" \
     -d '{
       "username": "john_doe",
       "password": "secure_password123",
       "api_key": ""
     }'

Response

Success (200 OK)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "name": "John Doe"
}

Field	Type	Description
token	string	JWT token for authentication
name	string	User's display name (optional)

Error Response Format

Error responses are returned as plain text messages, not JSON format.

Error Responses

400 Bad Request - Incomplete Data

LOG_ON_DATA_INCOMPLETE

401 Unauthorized - Invalid Credentials

FAIL

403 Forbidden - Feature Not Licensed

API feature not licensed

500 Internal Server Error

Internal server error message (plain text)

Using the JWT Token

Once you receive the JWT token from the login endpoint, include it in the Authorization header for all subsequent API requests:

Header Format

Authorization: Bearer YOUR_JWT_TOKEN

Example Authenticated Request

curl -X GET "http://your-server-ip:port/api/users/me" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
     -H "Content-Type: application/json"

JWT Token Details

The returned JWT token contains the following claims:

• username - The authenticated user's username
• scopes - Array of permissions/scopes for the user

Security Considerations

• HTTPS Recommended: Always use HTTPS in production to protect credentials
• Token Expiration: JWT tokens have an expiration time, after which you'll need to login again
• Secure Storage: Store JWT tokens securely on the client side
• Token Validation: The server validates the JWT token on each request

Complete Authentication Flow

1. Login: Send credentials to /api/login
2. Receive Token: Get JWT token in response
3. Store Token: Securely store the token on client
4. Use Token: Include token in Authorization header for API requests
5. Handle Expiration: Re-authenticate when token expires

Example Implementation

// Step 1: Login
const loginResponse = await fetch('http://your-server-ip:port/api/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'john_doe',
    password: 'secure_password123',
    api_key: ''
  })
});

const { token } = await loginResponse.json();

// Step 2: Use token for authenticated requests
const userResponse = await fetch('http://your-server-ip:port/api/users/me', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const user = await userResponse.json();