Skip to main content
The Peers API allows you to manage devices (peers) in your NetBird network, including updating configurations, approving peers, and managing peer connectivity.

​
List All Peers

Returns a list of all peers in your network. 
GET /api/peers
​
name
string
Filter peers by name
​
ip
string
Filter peers by IP address
curl -X GET https://api.netbird.io/api/peers \
  -H "Authorization: Token nbp_YOUR_TOKEN"
​
id
string
Unique peer identifier
​
name
string
Peer’s hostname or custom name
​
ip
string
Peer’s assigned NetBird IP address
​
connection_ip
string
Peer’s public connection IP address
​
connected
boolean
Peer to Management connection status
​
last_seen
string
Last time peer connected to management service (ISO 8601)
​
os
string
Peer’s operating system and version
​
version
string
NetBird daemon version running on the peer
​
groups
array
Groups that the peer belongs to
​
ssh_enabled
boolean
Indicates if SSH server is enabled on this peer
​
dns_label
string
Peer’s FQDN for DNS resolution
​
approval_required
boolean
(Cloud only) Indicates if peer needs approval

​
Get a Peer

Retrieve detailed information about a specific peer. 
GET /api/peers/{peerId}
​
peerId
string
required
The unique identifier of the peer
Example
curl -X GET https://api.netbird.io/api/peers/chacbco6lnnbn6cg5s90 \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Update a Peer

Update peer configuration including name, SSH status, and expiration settings. 
PUT /api/peers/{peerId}
​
peerId
string
required
The unique identifier of the peer
​
name
string
required
Peer’s hostname or custom name
​
ssh_enabled
boolean
required
Enable or disable SSH server on this peer
​
login_expiration_enabled
boolean
required
Enable or disable login expiration for this peer
​
inactivity_expiration_enabled
boolean
required
Enable or disable inactivity expiration for this peer
​
approval_required
boolean
(Cloud only) Indicates if peer needs approval
​
ip
string
Custom IP address for the peer (IPv4 format)
curl -X PUT https://api.netbird.io/api/peers/chacbco6lnnbn6cg5s90 \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-server-01",
    "ssh_enabled": true,
    "login_expiration_enabled": false,
    "inactivity_expiration_enabled": false
  }'

​
Delete a Peer

Remove a peer from the network. 
DELETE /api/peers/{peerId}
​
peerId
string
required
The unique identifier of the peer
Example
curl -X DELETE https://api.netbird.io/api/peers/chacbco6lnnbn6cg5s90 \
  -H "Authorization: Token nbp_YOUR_TOKEN"
Deleting a peer will:
  • Remove it from all groups
  • Disconnect it from the network
  • Remove it from all policies
This action cannot be undone.

​
List Accessible Peers

Returns a list of peers that a specific peer can connect to based on policies. 
GET /api/peers/{peerId}/accessible-peers
​
peerId
string
required
The unique identifier of the peer
curl -X GET https://api.netbird.io/api/peers/chacbco6lnnbn6cg5s90/accessible-peers \
  -H "Authorization: Token nbp_YOUR_TOKEN"

​
Create Temporary Access Peer

Create a temporary access peer for short-term access to a specific peer. The temporary peer and its policies are automatically deleted after it disconnects. 
POST /api/peers/{peerId}/temporary-access
​
peerId
string
required
The unique identifier of the peer to grant access to
​
name
string
required
Temporary peer’s hostname
​
wg_pub_key
string
required
WireGuard public key of the temporary peer
​
rules
array
required
List of access rules (e.g., [“tcp/80”, “tcp/443”])
curl -X POST https://api.netbird.io/api/peers/chacbco6lnnbn6cg5s90/temporary-access \
  -H "Authorization: Token nbp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "temp-access-001",
    "wg_pub_key": "n0r3pL4c3h0ld3rK3y==",
    "rules": ["tcp/22", "tcp/443"]
  }'
Temporary access peers are designed for support sessions, debugging, or temporary contractor access. They automatically clean up when disconnected.

​
Peer Status Indicators

Connected

Peer is online and connected to the management server

Disconnected

Peer is offline or hasn’t connected recently

Login Expired

User needs to re-authenticate on this peer

Pending Approval

Peer requires admin approval before joining

​
Peer Features

​
SSH Access

Enable SSH access to peers through NetBird: 
{
  "ssh_enabled": true
}
When enabled, you can SSH to peers using their NetBird IP or DNS name: 
ssh [email protected]
ssh [email protected]

​
Login Expiration

Force periodic re-authentication: 
{
  "login_expiration_enabled": true
}
Expiration period is configured globally in account settings.

​
Inactivity Expiration

Automatically disconnect inactive peers: 
{
  "inactivity_expiration_enabled": true
}

Build docs developers (and LLMs) love

Get started for freeTalk to us