Peers API

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

string

Filter peers by name

string

Filter peers by IP address

curl -X GET https://api.netbird.io/api/peers \
  -H "Authorization: Token nbp_YOUR_TOKEN"

curl -X GET "https://api.netbird.io/api/peers?name=laptop-01" \
  -H "Authorization: Token nbp_YOUR_TOKEN"

[
  {
    "id": "chacbco6lnnbn6cg5s90",
    "name": "laptop-01",
    "ip": "100.64.0.1",
    "connection_ip": "203.0.113.42",
    "connected": true,
    "last_seen": "2023-05-05T10:05:26.420578Z",
    "os": "darwin 13.2.1",
    "kernel_version": "23.2.0",
    "version": "0.14.0",
    "groups": [
      {
        "id": "ch8i4ug6lnn4g9hqv7m0",
        "name": "developers",
        "peers_count": 5
      }
    ],
    "ssh_enabled": true,
    "user_id": "google-oauth2|277474792786460067937",
    "hostname": "johns-macbook",
    "dns_label": "laptop-01.netbird.cloud",
    "login_expiration_enabled": false,
    "login_expired": false,
    "last_login": "2023-05-05T09:00:35.477782Z",
    "approval_required": false,
    "accessible_peers_count": 12
  }
]

string

Unique peer identifier

string

Peer’s hostname or custom name

string

Peer’s assigned NetBird IP address

string

Peer’s public connection IP address

boolean

Peer to Management connection status

string

Last time peer connected to management service (ISO 8601)

string

Peer’s operating system and version

string

NetBird daemon version running on the peer

array

Groups that the peer belongs to

boolean

Indicates if SSH server is enabled on this peer

string

Peer’s FQDN for DNS resolution

boolean

(Cloud only) Indicates if peer needs approval

Get a Peer

Retrieve detailed information about a specific peer.

GET /api/peers/{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}

string

required

The unique identifier of the peer

string

required

Peer’s hostname or custom name

boolean

required

Enable or disable SSH server on this peer

Enable or disable login expiration for this peer

boolean

required

Enable or disable inactivity expiration for this peer

boolean

(Cloud only) Indicates if peer needs approval

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
  }'

{
  "id": "chacbco6lnnbn6cg5s90",
  "name": "production-server-01",
  "ip": "100.64.0.1",
  "ssh_enabled": true,
  "login_expiration_enabled": false,
  "inactivity_expiration_enabled": false,
  "connected": true,
  "last_seen": "2023-05-05T10:05:26.420578Z"
}

Delete a Peer

Remove a peer from the network.

DELETE /api/peers/{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

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"

[
  {
    "id": "chacbco6lnnbn6cg5s91",
    "name": "server-01",
    "ip": "100.64.0.15",
    "dns_label": "server-01.netbird.cloud",
    "user_id": "google-oauth2|123456",
    "os": "linux",
    "country_code": "US",
    "city_name": "New York",
    "connected": true,
    "last_seen": "2023-05-05T10:05:26.420578Z"
  }
]

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

string

required

The unique identifier of the peer to grant access to

string

required

Temporary peer’s hostname

string

required

WireGuard public key of the temporary peer

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"]
  }'

{
  "id": "chacbco6lnnbn6cg5s92",
  "name": "temp-access-001",
  "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 user@laptop-01.netbird.cloud
ssh user@100.64.0.1

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
}

Getting Started

Resources

List All Peers

Get a Peer

Update a Peer

Delete a Peer

List Accessible Peers

Create Temporary Access Peer

Peer Status Indicators

Connected

Disconnected

Login Expired

Pending Approval

Peer Features

SSH Access

Inactivity Expiration

​List All Peers

​Get a Peer

​Update a Peer

​Delete a Peer

​List Accessible Peers

​Create Temporary Access Peer

​Peer Status Indicators

Connected

Disconnected

Login Expired

Pending Approval

​Peer Features

​SSH Access

​Login Expiration

​Inactivity Expiration

List All Peers

Get a Peer

Update a Peer

Delete a Peer

List Accessible Peers

Create Temporary Access Peer

Peer Status Indicators

Peer Features

SSH Access

Login Expiration

Inactivity Expiration