Security API Reference

NetBird extends the management REST API with fields for AES tunnel configuration, DSKE security hubs, and peer security status.

Account Settings

AES DNS Domain

Configure the DNS domain used for AES IP resolution.

Endpoint: PUT /api/accounts/{accountId}

Request body:

{
  "settings": {
    "aes_dns_domain": "secure.myorg.com"
  }
}

Response (settings section):

{
  "settings": {
    "dns_domain": "netbird.cloud",
    "aes_dns_domain": "secure.myorg.com"
  }
}

Behavior:

• If empty or unset, defaults to aes.<dns_domain>
• Can be overridden per-account via this API
• Management server flag --aes-dns-domain sets the default for all accounts
• Changes are logged as account.aes.dns.domain.update activity events

Precedence (highest first):

1. Per-account API setting
2. Management server CLI flag
3. Automatic default

Peer Fields

The following fields are added to peer responses for AES and DSKE features.

Endpoints: GET /api/peers, GET /api/peers/{id}, PUT /api/peers/{id}

Response Fields

Example Peer Response

{
  "id": "abc123",
  "name": "my-server",
  "ip": "100.64.0.1",
  "aes_ip": "100.64.128.1",
  "aes_exempt": false,
  "dske_security_hub": false,
  "aes_dns_label": "my-server.aes.netbird.cloud",
  "connected": true,
  ...
}

Updating Peer Security Properties

# Mark a peer as AES-exempt
curl -X PUT "https://management.example.com/api/peers/{peerId}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"aes_exempt": true}'

# Mark a peer as a security hub
curl -X PUT "https://management.example.com/api/peers/{peerId}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"dske_security_hub": true}'

Peer Type Summary

AES DNS Zone

The management server generates DNS zones for both WireGuard and AES IPs:

Reverse DNS (PTR records) for the AES IP range are generated automatically on the client side.

Activity Events

Event metadata includes old_aes_dns_domain and new_aes_dns_domain values.