Get Settings

Retrieve system settings and configuration based on user permissions and scopes.

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

Request

GET /api/settings

Authentication Required: Must include JWT token in Authorization header.

Authorization & Scopes

The endpoint requires one of the following scopes:

• settings - Returns full settings structure
• events - Returns only visible receivers
• objects - Returns only visible receivers

Example Request

curl -X GET "http://your-server-ip:port/api/settings" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

The response varies based on the user's scopes:

User with settings scope

Returns the complete settings structure:

{
  "version": 1,
  "general": {
    "server_name": "IPCom Server",
    "timezone": "Europe/Vilnius",
    "log_level": "info"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "ipcom_db"
  },
  "api": {
    "port": 8080,
    "enable_ssl": true,
    "ssl_cert_path": "/etc/ssl/certs/api.crt"
  },
  "receivers": [
    {
      "id": 1,
      "name": "Receiver1",
      "type": "TCP",
      "port": 9001
    },
    {
      "id": 2,
      "name": "Receiver2",
      "type": "UDP",
      "port": 9002
    }
  ],
  "users": [
    {
      "id": 1,
      "username": "admin",
      "scopes": ["settings", "users", "events", "objects"]
    }
  ],
  "ignorable_startup_events": [
    "SYSTEM_START",
    "CONFIG_RELOAD"
  ],
  "tracker": {
    "enable_tracking": true,
    "tracking_interval": 30,
    "max_devices": 1000
  },
  "internal_events": [
    {
      "type": "heartbeat",
      "interval": 60
    }
  ],
  "outputs": [
    {
      "id": 1,
      "name": "TCP_Output",
      "type": "TCP",
      "destination": "192.168.1.100:9000"
    }
  ],
  "device_status_output": {
    "enabled": true,
    "interval": 300,
    "format": "json"
  },
  "com_terminals": [
    {
      "id": 1,
      "name": "Terminal1",
      "port": "/dev/ttyS0",
      "baud_rate": 9600
    }
  ]
}

User with only events or objects scope

Returns only visible receivers:

{
  "visible_receivers": [
    {
      "id": 1,
      "name": "Receiver1"
    },
    {
      "id": 2,
      "name": "Receiver2"
    }
  ]
}

Response Structure

Full Settings Response

Field	Type	Description	Required Scope
version	int	Settings schema version	settings
general	object	General server configuration	settings
database	object	Database connection settings	settings
api	object	API server configuration	settings
receivers	array	Receiver configurations	settings
users	array	User accounts and permissions	settings + users
ignorable_startup_events	array	Events to ignore on startup	settings
tracker	object	Device tracking configuration	settings
internal_events	array	Internal system event settings	settings
outputs	array	Output destination configurations	settings
device_status_output	object	Device status output settings	settings
com_terminals	array	Serial communication terminals	settings

Limited Response (events/objects scope)

Field	Type	Description
visible_receivers	array	List of receivers visible to user

Receiver Object

Field	Type	Description
id	int	Receiver identifier
name	string	Receiver name

Authorization Rules

Settings Scope

• Full access: Returns complete settings structure
• Users section: Only included if user also has users scope
• All other sections: Included with settings scope

Events/Objects Scope

• Limited access: Only returns visible_receivers
• No sensitive data: Configuration details are hidden
• Receiver visibility: Based on user's assigned receivers

No Valid Scope

• Access denied: Returns 403 Forbidden
• Required scopes: Must have settings, events, or objects

Error Responses

All error responses are returned as plain text:

401 Unauthorized

NOT_LOGGED_IN

403 Forbidden

FORBIDDEN

500 Internal Server Error

E_3

Use Cases

System Administration

# Get full system settings (requires settings scope)
curl -X GET "http://your-server-ip:port/api/settings" \
     -H "Authorization: Bearer ADMIN_JWT_TOKEN"

Receiver Management

# Get visible receivers (requires events or objects scope)
curl -X GET "http://your-server-ip:port/api/settings" \
     -H "Authorization: Bearer USER_JWT_TOKEN" | jq '.visible_receivers'

Configuration Validation

# Check specific configuration section
curl -X GET "http://your-server-ip:port/api/settings" \
     -H "Authorization: Bearer ADMIN_JWT_TOKEN" | jq '.database'

Security Considerations

• Scope-based access: Different users see different data based on scopes
• Sensitive information: Full settings contain database credentials and API keys
• User isolation: Limited scope users only see relevant receivers
• Authentication required: All requests must include valid JWT token

Integration Examples

Monitoring Dashboard

// Check if user has admin access
const response = await fetch('/api/settings', {
  headers: { 'Authorization': `Bearer ${token}` }
});

const settings = await response.json();

if (settings.version) {
  // User has settings scope - show admin interface
  showAdminDashboard(settings);
} else if (settings.visible_receivers) {
  // User has limited scope - show user interface
  showUserDashboard(settings.visible_receivers);
}

Configuration Backup

# Backup current settings
curl -X GET "http://your-server-ip:port/api/settings" \
     -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
     -o settings_backup_$(date +%Y%m%d).json

Notes

• Scope hierarchy: settings scope provides most access, events/objects provide limited access
• Dynamic response: Response structure depends on user permissions
• Users section: Only visible with both settings and users scopes
• Plain text errors: Error responses are not in JSON format
• Real-time data: Settings reflect current server configuration