NetBird Peers API
Interact with and view information about peers.
OpenAPI Specification
openapi: 3.1.0
info:
title: NetBird REST Accounts Peers API
description: API to manipulate groups, rules, policies and retrieve information about peers and users
version: 0.0.1
servers:
- url: https://api.netbird.io
description: Default server
security:
- BearerAuth: []
- TokenAuth: []
tags:
- name: Peers
description: Interact with and view information about peers.
paths:
/api/peers:
get:
summary: List all Peers
description: Returns a list of all peers
tags:
- Peers
parameters:
- in: query
name: name
schema:
type: string
description: Filter peers by name
- in: query
name: ip
schema:
type: string
description: Filter peers by IP address
security:
- BearerAuth: []
- TokenAuth: []
responses:
'200':
description: A JSON Array of Peers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PeerBatch'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_error'
/api/peers/{peerId}:
get:
summary: Retrieve a Peer
description: Get information about a peer
tags:
- Peers
security:
- BearerAuth: []
- TokenAuth: []
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
responses:
'200':
description: A Peer object
content:
application/json:
schema:
$ref: '#/components/schemas/Peer'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_error'
put:
summary: Update a Peer
description: Update information about a peer
tags:
- Peers
security:
- BearerAuth: []
- TokenAuth: []
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
requestBody:
description: update a peer
content:
application/json:
schema:
$ref: '#/components/schemas/PeerRequest'
responses:
'200':
description: A Peer object
content:
application/json:
schema:
$ref: '#/components/schemas/Peer'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_error'
delete:
summary: Delete a Peer
description: Delete a peer
tags:
- Peers
security:
- BearerAuth: []
- TokenAuth: []
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
responses:
'200':
description: Delete status code
content: {}
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_error'
/api/peers/{peerId}/accessible-peers:
get:
summary: List accessible Peers
description: Returns a list of peers that the specified peer can connect to within the network.
tags:
- Peers
security:
- BearerAuth: []
- TokenAuth: []
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
responses:
'200':
description: A JSON Array of Accessible Peers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AccessiblePeer'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_error'
/api/peers/{peerId}/temporary-access:
post:
summary: Create a Temporary Access Peer
description: Creates a temporary access peer that can be used to access this peer and this peer only. The temporary access peer and its access policies will be automatically deleted after it disconnects.
tags:
- Peers
security:
- BearerAuth: []
- TokenAuth: []
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
requestBody:
description: Temporary Access Peer create request
content:
application/json:
schema:
$ref: '#/components/schemas/PeerTemporaryAccessRequest'
responses:
'200':
description: Temporary Access Peer response
content:
application/json:
schema:
$ref: '#/components/schemas/PeerTemporaryAccessResponse'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_error'
components:
responses:
bad_request:
description: Bad Request
content: {}
internal_error:
description: Internal Server Error
content: {}
requires_authentication:
description: Requires authentication
content: {}
forbidden:
description: Forbidden
content: {}
schemas:
AccessiblePeer:
allOf:
- $ref: '#/components/schemas/PeerMinimum'
- type: object
properties:
ip:
description: Peer's IP address
type: string
example: 10.64.0.1
dns_label:
description: Peer's DNS label is the parsed peer name for domain resolution. It is used to form an FQDN by appending the account's domain to the peer label. e.g. peer-dns-label.netbird.cloud
type: string
example: stage-host-1.netbird.cloud
user_id:
description: User ID of the user that enrolled this peer
type: string
example: google-oauth2|277474792786460067937
os:
description: Peer's operating system and version
type: string
example: linux
country_code:
$ref: '#/components/schemas/CountryCode'
city_name:
$ref: '#/components/schemas/CityName'
geoname_id:
description: Unique identifier from the GeoNames database for a specific geographical location.
type: integer
example: 2643743
connected:
description: Peer to Management connection status
type: boolean
example: true
last_seen:
description: Last time peer connected to Netbird's management service
type: string
format: date-time
example: '2023-05-05T10:05:26.420578Z'
required:
- ip
- dns_label
- user_id
- os
- country_code
- city_name
- geoname_id
- connected
- last_seen
PeerRequest:
type: object
properties:
name:
type: string
example: stage-host-1
ssh_enabled:
type: boolean
example: true
login_expiration_enabled:
type: boolean
example: false
inactivity_expiration_enabled:
type: boolean
example: false
approval_required:
description: (Cloud only) Indicates whether peer needs approval
type: boolean
example: true
ip:
description: Peer's IP address
type: string
format: ipv4
example: 100.64.0.15
required:
- name
- ssh_enabled
- login_expiration_enabled
- inactivity_expiration_enabled
PeerTemporaryAccessResponse:
type: object
properties:
name:
description: Peer's hostname
type: string
example: temp-host-1
id:
description: Peer ID
type: string
example: chacbco6lnnbn6cg5s90
rules:
description: List of temporary access rules
type: array
items:
type: string
example: tcp/80
required:
- name
- id
- rules
GroupMinimum:
type: object
properties:
id:
description: Group ID
type: string
example: ch8i4ug6lnn4g9hqv7m0
name:
description: Group Name identifier
type: string
example: devs
peers_count:
description: Count of peers associated to the group
type: integer
example: 2
resources_count:
description: Count of resources associated to the group
type: integer
example: 5
issued:
description: How the group was issued (api, integration, jwt)
type: string
enum:
- api
- integration
- jwt
example: api
required:
- id
- name
- peers_count
- resources_count
PeerMinimum:
type: object
properties:
id:
description: Peer ID
type: string
example: chacbco6lnnbn6cg5s90
name:
description: Peer's hostname
type: string
example: stage-host-1
required:
- id
- name
PeerLocalFlags:
type: object
properties:
rosenpass_enabled:
description: Indicates whether Rosenpass is enabled on this peer
type: boolean
example: true
rosenpass_permissive:
description: Indicates whether Rosenpass is in permissive mode or not
type: boolean
example: false
server_ssh_allowed:
description: Indicates whether SSH access this peer is allowed or not
type: boolean
example: true
disable_client_routes:
description: Indicates whether client routes are disabled on this peer or not
type: boolean
example: false
disable_server_routes:
description: Indicates whether server routes are disabled on this peer or not
type: boolean
example: false
disable_dns:
description: Indicates whether DNS management is disabled on this peer or not
type: boolean
example: false
disable_firewall:
description: Indicates whether firewall management is disabled on this peer or not
type: boolean
example: false
block_lan_access:
description: Indicates whether LAN access is blocked on this peer when used as a routing peer
type: boolean
example: false
block_inbound:
description: Indicates whether inbound traffic is blocked on this peer
type: boolean
example: false
lazy_connection_enabled:
description: Indicates whether lazy connection is enabled on this peer
type: boolean
example: false
CountryCode:
description: 2-letter ISO 3166-1 alpha-2 code that represents the country
type: string
example: DE
Peer:
allOf:
- $ref: '#/components/schemas/PeerMinimum'
- type: object
properties:
created_at:
description: Peer creation date (UTC)
type: string
format: date-time
example: '2023-05-05T09:00:35.477782Z'
ip:
description: Peer's IP address
type: string
example: 10.64.0.1
connection_ip:
description: Peer's public connection IP address
type: string
example: 35.64.0.1
connected:
description: Peer to Management connection status
type: boolean
example: true
last_seen:
description: Last time peer connected to Netbird's management service
type: string
format: date-time
example: '2023-05-05T10:05:26.420578Z'
os:
description: Peer's operating system and version
type: string
example: Darwin 13.2.1
kernel_version:
description: Peer's operating system kernel version
type: string
example: 23.2.0
geoname_id:
description: Unique identifier from the GeoNames database for a specific geographical location.
type: integer
example: 2643743
version:
description: Peer's daemon or cli version
type: string
example: 0.14.0
groups:
description: Groups that the peer belongs to
type: array
items:
$ref: '#/components/schemas/GroupMinimum'
ssh_enabled:
description: Indicates whether SSH server is enabled on this peer
type: boolean
example: true
user_id:
description: User ID of the user that enrolled this peer
type: string
example: google-oauth2|277474792786460067937
hostname:
description: Hostname of the machine
type: string
example: stage-host-1
ui_version:
description: Peer's desktop UI version
type: string
example: 0.14.0
dns_label:
description: Peer's DNS label is the parsed peer name for domain resolution. It is used to form an FQDN by appending the account's domain to the peer label. e.g. peer-dns-label.netbird.cloud
type: string
example: stage-host-1.netbird.cloud
login_expiration_enabled:
description: Indicates whether peer login expiration has been enabled or not
type: boolean
example: false
login_expired:
description: Indicates whether peer's login expired or not
type: boolean
example: false
last_login:
description: Last time this peer performed log in (authentication). E.g., user authenticated.
type: string
format: date-time
example: '2023-05-05T09:00:35.477782Z'
inactivity_expiration_enabled:
description: Indicates whether peer inactivity expiration has been enabled or not
type: boolean
example: false
approval_required:
description: (Cloud only) Indicates whether peer needs approval
type: boolean
example: true
disapproval_reason:
description: (Cloud only) Reason why the peer requires approval
type: string
country_code:
$ref: '#/components/schemas/CountryCode'
city_name:
$ref: '#/components/schemas/CityName'
serial_number:
description: System serial number
type: string
example: C02XJ0J0JGH7
extra_dns_labels:
description: Extra DNS labels added to the peer
type: array
items:
type: string
example: stage-host-1
ephemeral:
description: Indicates whether the peer is ephemeral or not
type: boolean
example: false
local_flags:
$ref: '#/components/schemas/PeerLocalFlags'
required:
- city_name
- connected
- connection_ip
- country_code
- created_at
- dns_label
- geoname_id
- groups
- hostname
- ip
- kernel_version
- last_login
- last_seen
- login_expiration_enabled
- login_expired
- inactivity_expiration_enabled
- os
- ssh_enabled
- user_id
- version
- ui_version
- approval_required
- serial_number
- extra_dns_labels
- ephemeral
PeerTemporaryAccessRequest:
type: object
properties:
name:
description: Peer's hostname
type: string
example: temp-host-1
wg_pub_key:
description: Peer's WireGuard public key
type: string
example: n0r3pL4c3h0ld3rK3y==
rules:
description: List of temporary access rules
type: array
items:
type: string
example: tcp/80
required:
- name
- wg_pub_key
- rules
PeerBatch:
allOf:
- $ref: '#/components/schemas/Peer'
- type: object
properties:
created_at:
description: Peer creation date (UTC)
type: string
format: date-time
example: '2023-05-05T09:00:35.477782Z'
accessible_peers_count:
description: Number of accessible peers
type: integer
example: 5
required:
- created_at
- accessible_peers_count
CityName:
description: Commonly used English name of the city
type: string
example: Berlin
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
TokenAuth:
type: apiKey
in: header
name: Authorization
description: Enter the token with the `Token` prefix, e.g. "Token nbp_F3f0d.....".