Connections API

View and manage connected TAK clients

The Connections API provides endpoints for viewing information about currently connected TAK clients.

Get Connected Clients

Retrieve a list of all currently connected TAK clients.

curl

curl -X GET "http://localhost:19023/Clients" \
  -H "X-Forwarded-For: 127.0.0.1"

Authentication

This endpoint requires IP-based authentication. The requesting IP address must be in the AllowedCLIIPs configuration list.

Response

Returns an array of connected client objects serialized to JSON.

array · array

Array of connected client objects

Show client object

uid · string

Unique identifier for the connected client

callsign · string

Client’s callsign/display name

team · string

Team/group affiliation

role · string

Client’s role in the team

address · string

IP address of the connected client

lastSeen · string

ISO 8601 timestamp of last activity

Response Example

[
  {
    "uid": "client-uid-123",
    "callsign": "ALPHA-1",
    "team": "Cyan",
    "role": "Team Leader",
    "address": "192.168.1.100",
    "lastSeen": "2024-03-04T12:30:45Z"
  },
  {
    "uid": "client-uid-456",
    "callsign": "BRAVO-2",
    "team": "Red",
    "role": "Rifleman",
    "address": "192.168.1.101",
    "lastSeen": "2024-03-04T12:31:20Z"
  }
]

IP-Based Authentication

The /Clients endpoint uses IP-based authentication for security. To configure allowed IPs:

1. Edit your FreeTAKServer configuration file
2. Add IP addresses to the AllowedCLIIPs list:

AllowedCLIIPs:
  - 127.0.0.1
  - 192.168.1.0/24
  - 10.0.0.0/8

Behind a Proxy

If FreeTAKServer is behind a reverse proxy (nginx, Apache, etc.), ensure the proxy forwards the real client IP using headers like:

• X-Forwarded-For
• X-Real-IP

The server will check these headers against the allowed IP list.

Connection Management

The connections API provides read-only access to connection information. To manage connections:

• Disconnect clients: Use administrative commands or terminate connections at the CoT service level
• Monitor activity: Use the connection timestamp to detect stale clients
• Track teams: Group clients by team affiliation

Use Cases

Server Monitoring

Query the connections endpoint periodically to:

• Monitor server load (number of connected clients)
• Detect connectivity issues
• Track team member availability
• Generate activity reports

Dashboard Integration

Integrate with monitoring dashboards:

const response = await fetch('http://localhost:19023/Clients', {
  headers: {
    'X-Forwarded-For': '127.0.0.1'
  }
});
const clients = await response.json();
console.log(`Connected clients: ${clients.length}`);

Team Coordination

Use connection data to:

• Verify team members are online before missions
• Track team composition in real-time
• Identify missing or disconnected members

Connection State

Client connection information is maintained by FreeTAKServer’s CoT services:

• TCP CoT Service: Port 8087 (default)
• SSL CoT Service: Port 8089 (default)

Clients send periodic position updates (SA - Situation Awareness messages) which update their lastSeen timestamp.

Error Responses

401 Unauthorized

{
  "message": "endpoint can only be accessed by approved IPs"
}

Returned when the requesting IP is not in the AllowedCLIIPs list.

500 Internal Server Error

{
  "message": "An error occurred retrieving client details."
}

Returned when an internal error occurs while retrieving connection information.

Related Endpoints

For user management and authentication, see:

• User Management API (certificate generation, user creation)
• Authentication endpoints

Security Considerations

1. Restrict Access: Only add trusted IPs to AllowedCLIIPs
2. Monitor Usage: Log all requests to this endpoint
3. Regular Audits: Periodically review the allowed IP list
4. Network Segmentation: Place FreeTAKServer in a protected network segment
5. Rate Limiting: Consider implementing rate limiting for this endpoint