Update Settings

Update system settings and configuration. Only users with the settings scope can modify settings.

📖 Configuration Reference: For detailed information about all configuration fields, structure, and valid values, see the Complete Configuration Documentation.

Request

PUT /api/settings

Authentication Required: Must include JWT token in Authorization header.

Required Scope: settings

Content-Type: application/json

Request Body

A JSON object containing one or more of the following top-level keys (all optional, only provided fields are updated):

{
  "api": {
    "api_port": 8080,
    "api_http_port": 8081,
    "api_jwt_secret": "your-64-character-jwt-secret-key-here-must-be-exactly-64-chars",
    "private_key": "/path/to/private.key",
    "public_key": "/path/to/public.key"
  },
  "database": {
    "enabled": true,
    "sqluser": "ipcom_user",
    "sqlpass": "secure_password",
    "sqlhost": "localhost",
    "sqldatabase": "ipcom_db",
    "sqlport": 3306,
    "remove_lost_objects_age": 30,
    "remove_events_age": 365,
    "device_session_log_count": 10
  },
  "device_status_output": {
    "enabled": true,
    "port": 9000,
    "encryption_enabled": false,
    "encryption_key": "16-character-key"
  },
  "general": {
    "instance_name": "IPCom Server",
    "synchronize_device_time_interval": 3600
  },
  "ignorable_startup_events": [
    {
      "event_code": "0x001",
      "group_no": "0x01",
      "zone_no": "0x001"
    }
  ],
  "internal_events": [
    {
      "type": "heartbeat",
      "classificator": "E",
      "event_code": "0x100",
      "group_no": "0x01",
      "zone_no": "0x001",
      "name": "System Heartbeat"
    }
  ],
  "outputs": [
    {
      "id": 1,
      "name": "TCP_Output",
      "type": 1,
      "protocol": "TCP",
      "identificator": "output1",
      "oid": 12345,
      "receiver_number": 1,
      "line_number": 1
    }
  ],
  "receivers": {
    "tcp_receivers": [
      {
        "id": 1,
        "name": "Receiver1",
        "port": 9001,
        "encryption_password": "secret"
      }
    ],
    "udp_receivers": [
      {
        "id": 2,
        "name": "Receiver2",
        "port": 9002
      }
    ]
  },
  "tracker": {
    "timeout_multiplier": 3,
    "sms_timeout_multiplier": 5,
    "timeout_tolerance": 30,
    "sms_timeout_tolerance": 60,
    "event_count_for_restore": 3,
    "event_count_for_restore_sms": 2
  },
  "users": [
    {
      "id": 1,
      "login": "admin",
      "password": "secure_password",
      "token_time": 1440,
      "scopes": ["settings", "users", "events", "objects"],
      "visible_receivers": {
        "all": true,
        "custom": []
      }
    }
  ]
}

Example Request

curl -X PUT "http://your-server-ip:port/api/settings" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "general": {
         "instance_name": "My IPCom Server"
       },
       "api": {
         "api_port": 8080
       }
     }'

Response

Success (200 OK)

{
  "success": true
}

Error Responses

All error responses are returned as plain text:

401 Unauthorized

NOT_LOGGED_IN

403 Forbidden

FORBIDDEN

500 Internal Server Error

E_3

Validation Rules

All updated fields are validated before changes are applied. Invalid data will result in a plain text error response.

API Settings Validation

• api_port and api_http_port must be between 1 and 65535
• api_jwt_secret must be exactly 64 characters and not empty
• private_key and public_key must be non-empty and point to valid PEM files

Database Settings Validation

• If enabled, sqluser, sqlpass, sqlhost, and sqldatabase must be non-empty
• sqlport must be between 1 and 65535 (default 3306 if 0)
• Database connection is validated for connectivity
• remove_lost_objects_age and remove_events_age must be between 1 and 365 days
• device_session_log_count must be between 1 and 25

General Settings Validation

• instance_name must be non-empty
• synchronize_device_time_interval must be greater than 0

Receivers Validation

• Each receiver must have a unique, non-zero id and non-empty name
• TCP/UDP ports must be between 1 and 65535 and unique per category
• Encryption password must be either 6 or 16 characters for IP/Modem receivers
• COM/Modem receivers must have valid port_id and reference existing COM terminals

Outputs Validation

• Each output must have a unique, non-zero id and non-empty name
• type, protocol, and identificator must be within allowed ranges
• oid, receiver_number, and line_number must be within allowed ranges
• SIA DC09 settings: encryption key must be valid if encryption is enabled
• Filters must have valid receiver numbers and settings

Users Validation

• Each user must have a unique, non-zero id, non-empty login and password
• token_time must be between 1 and 5,256,000 minutes (10 years)
• Scopes must be from the allowed set: settings, users, events, objects
• If visible_receivers.all is false, custom must not be empty
• User count may be limited by license

Tracker Settings Validation

• timeout_multiplier and sms_timeout_multiplier must be between 1 and 100
• timeout_tolerance and sms_timeout_tolerance must be between 0 and 3600
• event_count_for_restore and event_count_for_restore_sms must be between 1 and 10

Internal Events Validation

• type must be a valid enum value
• classificator must be "E" or "R"
• event_code, group_no, and zone_no must be valid hex strings and within allowed ranges
• name must be non-empty

Device Status Output Validation

• port must be between 1 and 65535
• If encryption is enabled, encryption_key must be exactly 16 characters

Ignorable Startup Events Validation

• event_code ≤ 0xFFF, group_no ≤ 0xFF, zone_no ≤ 0xFFF
• Each triplet (event_code, group_no, zone_no) must be unique

Update Examples

Update Server Name

curl -X PUT "http://your-server-ip:port/api/settings" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "general": {
         "instance_name": "Production IPCom Server"
       }
     }'

Update API Port

curl -X PUT "http://your-server-ip:port/api/settings" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "api": {
         "api_port": 9090
       }
     }'

Add New User

curl -X PUT "http://your-server-ip:port/api/settings" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "users": [
         {
           "id": 2,
           "login": "operator",
           "password": "operator_password",
           "token_time": 480,
           "scopes": ["events", "objects"],
           "visible_receivers": {
             "all": false,
             "custom": [1, 2]
           }
         }
       ]
     }'

Update Database Settings

curl -X PUT "http://your-server-ip:port/api/settings" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "database": {
         "enabled": true,
         "sqlhost": "db.example.com",
         "sqlport": 5432,
         "remove_events_age": 180
       }
     }'

Important Notes

• Partial updates: Only fields provided in the request are updated; others remain unchanged
• Settings scope required: Only users with settings scope can modify settings
• Validation: All fields are validated before applying changes
• Plain text errors: Error responses are not in JSON format
• Cross-validation: Receivers and outputs are cross-validated for consistency
• Immediate effect: Most settings take effect immediately; some may require restart