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.....".