netbird/shared/management/http/api/openapi.yml

openapi: 3.1.0
servers:
  - url: https://api.netbird.io
    description: Default server
info:
  title: NetBird REST API
  description: API to manipulate groups, rules, policies and retrieve information about peers and users
  version: 0.0.1
tags:
  - name: Users
    description: Interact with and view information about users.
  - name: Tokens
    description: Interact with and view information about tokens.
  - name: Peers
    description: Interact with and view information about peers.
  - name: Setup Keys
    description: Interact with and view information about setup keys.
  - name: Groups
    description: Interact with and view information about groups.
  - name: Policies
    description: Interact with and view information about policies.
  - name: Posture Checks
    description: Interact with and view information about posture checks.
  - name: Routes
    description: Interact with and view information about routes.
  - name: DNS
    description: Interact with and view information about DNS configuration.
  - name: DNS Zones
    description: Interact with and view information about custom DNS zones.
  - name: Events
    description: View information about the account and network events.
  - name: Accounts
    description: View information about the accounts.
  - name: Ingress Ports
    description: Interact with and view information about the ingress peers and ports.
    x-cloud-only: true
  - name: Identity Providers
    description: Interact with and view information about identity providers.
  - name: Reverse Proxy
    description: Interact with and view information about reverse proxies.
  - name: Instance
    description: Instance setup and status endpoints for initial configuration.
  - name: Jobs
    description: Interact with and view information about remote jobs.
    x-experimental: true

components:
  schemas:
    PasswordChangeRequest:
      type: object
      properties:
        old_password:
          description: The current password
          type: string
          example: "currentPassword123"
        new_password:
          description: The new password to set
          type: string
          example: "newSecurePassword456"
      required:
        - old_password
        - new_password
    WorkloadType:
      type: string
      description: |
         Identifies the type of workload the job will execute.
         Currently only `"bundle"` is supported.
      enum:
        - bundle
      example: "bundle"
    BundleParameters:
      type: object
      description: These parameters control what gets included in the bundle and how it is processed.
      properties:
        bundle_for:
          type: boolean
          description: Whether to generate a bundle for the given timeframe.
          example: true
        bundle_for_time:
          type: integer
          minimum: 1
          maximum: 5
          description: Time period in minutes for which to generate the bundle.
          example: 2
        log_file_count:
          type: integer
          minimum: 1
          maximum: 1000
          description: Maximum number of log files to include in the bundle.
          example: 100
        anonymize:
          type: boolean
          description: Whether sensitive data should be anonymized in the bundle.
          example: false
      required:
        - bundle_for
        - bundle_for_time
        - log_file_count
        - anonymize
    BundleResult:
      type: object
      properties:
        upload_key:
          type: string
          example: "upload_key_123"
          nullable: true
    BundleWorkloadRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WorkloadType'
        parameters:
          $ref: '#/components/schemas/BundleParameters'
      required:
      - type
      - parameters
    BundleWorkloadResponse:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WorkloadType'
        parameters:
          $ref: '#/components/schemas/BundleParameters'
        result:
          $ref: '#/components/schemas/BundleResult'
      required:
        - type
        - parameters
        - result
    WorkloadRequest:
      oneOf:
        - $ref: '#/components/schemas/BundleWorkloadRequest'
      discriminator:
        propertyName: type
        mapping:
          bundle: '#/components/schemas/BundleWorkloadRequest'
    WorkloadResponse:
      oneOf:
        - $ref: '#/components/schemas/BundleWorkloadResponse'
      discriminator:
        propertyName: type
        mapping:
          bundle: '#/components/schemas/BundleWorkloadResponse'
    JobRequest:
      type: object
      properties:
        workload:
          $ref: '#/components/schemas/WorkloadRequest'
      required:
        - workload
    JobResponse:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
        triggered_by:
          type: string
        status:
          type: string
          enum: [pending, succeeded, failed]
        failed_reason:
          type: string
          nullable: true
        workload:
          $ref: '#/components/schemas/WorkloadResponse'
      required:
        - id
        - created_at
        - status
        - triggered_by
        - workload
    Account:
      type: object
      properties:
        id:
          description: Account ID
          type: string
          example: ch8i4ug6lnn4g9hqv7l0
        settings:
          $ref: '#/components/schemas/AccountSettings'
        domain:
          description: Account domain
          type: string
          example: netbird.io
        domain_category:
          description: Account domain category
          type: string
          example: private
        created_at:
          description: Account creation date (UTC)
          type: string
          format: date-time
          example: "2023-05-05T09:00:35.477782Z"
        created_by:
          description: Account creator
          type: string
          example: google-oauth2|277474792786460067937
        onboarding:
          $ref: '#/components/schemas/AccountOnboarding'
      required:
        - id
        - settings
        - domain
        - domain_category
        - created_at
        - created_by
        - onboarding
    AccountOnboarding:
      type: object
      properties:
        signup_form_pending:
          description: Indicates whether the account signup form is pending
          type: boolean
          example: true
        onboarding_flow_pending:
          description: Indicates whether the account onboarding flow is pending
          type: boolean
          example: false
      required:
        - signup_form_pending
        - onboarding_flow_pending
    AccountSettings:
      type: object
      properties:
        peer_login_expiration_enabled:
          description: Enables or disables peer login expiration globally. After peer's login has expired the user has to log in (authenticate). Applies only to peers that were added by a user (interactive SSO login).
          type: boolean
          example: true
        peer_login_expiration:
          description: Period of time after which peer login expires (seconds).
          type: integer
          example: 43200
        peer_inactivity_expiration_enabled:
          description: Enables or disables peer inactivity expiration globally. After peer's session has expired the user has to log in (authenticate). Applies only to peers that were added by a user (interactive SSO login).
          type: boolean
          example: true
        peer_inactivity_expiration:
          description: Period of time of inactivity after which peer session expires (seconds).
          type: integer
          example: 43200
        regular_users_view_blocked:
          description: Allows blocking regular users from viewing parts of the system.
          type: boolean
          example: true
        groups_propagation_enabled:
          description: Allows propagate the new user auto groups to peers that belongs to the user
          type: boolean
          example: true
        jwt_groups_enabled:
          description: Allows extract groups from JWT claim and add it to account groups.
          type: boolean
          example: true
        jwt_groups_claim_name:
          description: Name of the claim from which we extract groups names to add it to account groups.
          type: string
          example: "roles"
        jwt_allow_groups:
          description: List of groups to which users are allowed access
          type: array
          items:
            type: string
            example: Administrators
        routing_peer_dns_resolution_enabled:
          description: Enables or disables DNS resolution on the routing peers
          type: boolean
          example: true
        dns_domain:
          description: Allows to define a custom dns domain for the account
          type: string
          example: my-organization.org
        network_range:
          description: Allows to define a custom network range for the account in CIDR format
          type: string
          format: cidr
          example: 100.64.0.0/16
        extra:
          $ref: '#/components/schemas/AccountExtraSettings'
        lazy_connection_enabled:
          x-experimental: true
          description: Enables or disables experimental lazy connection
          type: boolean
          example: true
        auto_update_version:
          description: Set Clients auto-update version. "latest", "disabled", or a specific version (e.g "0.50.1")
          type: string
          example: "0.51.2"
        embedded_idp_enabled:
          description: Indicates whether the embedded identity provider (Dex) is enabled for this account. This is a read-only field.
          type: boolean
          readOnly: true
          example: false
        local_auth_disabled:
          description: Indicates whether local (email/password) authentication is disabled. When true, users can only authenticate via external identity providers. This is a read-only field.
          type: boolean
          readOnly: true
          example: false
      required:
        - peer_login_expiration_enabled
        - peer_login_expiration
        - peer_inactivity_expiration_enabled
        - peer_inactivity_expiration
        - regular_users_view_blocked
    AccountExtraSettings:
      type: object
      properties:
        peer_approval_enabled:
          description: (Cloud only) Enables or disables peer approval globally. If enabled, all peers added will be in pending state until approved by an admin.
          type: boolean
          example: true
        user_approval_required:
          description: Enables manual approval for new users joining via domain matching. When enabled, users are blocked with pending approval status until explicitly approved by an admin.
          type: boolean
          example: false
        network_traffic_logs_enabled:
          description: Enables or disables network traffic logging. If enabled, all network traffic events from peers will be stored.
          type: boolean
          example: true
        network_traffic_logs_groups:
          description: Limits traffic logging to these groups. If unset all peers are enabled.
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        network_traffic_packet_counter_enabled:
          description: Enables or disables network traffic packet counter. If enabled, network packets and their size will be counted and reported. (This can have an slight impact on performance)
          type: boolean
          example: true
      required:
        - peer_approval_enabled
        - user_approval_required
        - network_traffic_logs_enabled
        - network_traffic_logs_groups
        - network_traffic_packet_counter_enabled
    AccountRequest:
      type: object
      properties:
        settings:
          $ref: '#/components/schemas/AccountSettings'
        onboarding:
          $ref: '#/components/schemas/AccountOnboarding'
      required:
        - settings
    User:
      type: object
      properties:
        id:
          description: User ID
          type: string
          example: google-oauth2|277474792786460067937
        email:
          description: User's email address
          type: string
          example: demo@netbird.io
        password:
          description: User's password. Only present when user is created (create user endpoint is called) and only when IdP supports user creation with password.
          type: string
          example: super_secure_password
        name:
          description: User's name from idp provider
          type: string
          example: Tom Schulz
        role:
          description: User's NetBird account role
          type: string
          example: admin
        status:
          description: User's status
          type: string
          enum: [ "active","invited","blocked" ]
          example: active
        last_login:
          description: Last time this user performed a login to the dashboard
          type: string
          format: date-time
          example: "2023-05-05T09:00:35.477782Z"
        auto_groups:
          description: Group IDs to auto-assign to peers registered by this user
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        is_current:
          description: Is true if authenticated user is the same as this user
          type: boolean
          readOnly: true
          example: true
        is_service_user:
          description: Is true if this user is a service user
          type: boolean
          readOnly: true
          example: false
        is_blocked:
          description: Is true if this user is blocked. Blocked users can't use the system
          type: boolean
          example: false
        pending_approval:
          description: Is true if this user requires approval before being activated. Only applicable for users joining via domain matching when user_approval_required is enabled.
          type: boolean
          example: false
        issued:
          description: How user was issued by API or Integration
          type: string
          example: api
        idp_id:
          description: Identity provider ID (connector ID) that the user authenticated with. Only populated for users with Dex-encoded user IDs.
          type: string
          example: okta-abc123
        permissions:
          $ref: '#/components/schemas/UserPermissions'
      required:
        - id
        - email
        - name
        - role
        - auto_groups
        - status
        - is_blocked
        - pending_approval
    UserPermissions:
      type: object
      properties:
        is_restricted:
          type: boolean
          description: Indicates whether this User's Peers view is restricted
        modules:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: boolean
            propertyNames:
              type: string
              description: The operation type
          propertyNames:
            type: string
            description: The module name
          example: {"networks": { "read": true, "create": false, "update": false, "delete": false}, "peers": { "read": false, "create": false, "update": false, "delete": false} }
      required:
        - modules
        - is_restricted
    UserRequest:
      type: object
      properties:
        role:
          description: User's NetBird account role
          type: string
          example: admin
        auto_groups:
          description: Group IDs to auto-assign to peers registered by this user
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        is_blocked:
          description: If set to true then user is blocked and can't use the system
          type: boolean
          example: false
      required:
        - role
        - auto_groups
        - is_blocked
    UserCreateRequest:
      type: object
      properties:
        email:
          description: User's Email to send invite to
          type: string
          example: demo@netbird.io
        name:
          description: User's full name
          type: string
          example: Tom Schulz
        role:
          description: User's NetBird account role
          type: string
          example: admin
        auto_groups:
          description: Group IDs to auto-assign to peers registered by this user
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        is_service_user:
          description: Is true if this user is a service user
          type: boolean
          example: false
      required:
        - role
        - auto_groups
        - is_service_user
    UserInviteCreateRequest:
      type: object
      description: Request to create a user invite link
      properties:
        email:
          description: User's email address
          type: string
          example: user@example.com
        name:
          description: User's full name
          type: string
          example: John Doe
        role:
          description: User's NetBird account role
          type: string
          example: user
        auto_groups:
          description: Group IDs to auto-assign to peers registered by this user
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        expires_in:
          description: Invite expiration time in seconds (default 72 hours)
          type: integer
          example: 259200
      required:
        - email
        - name
        - role
        - auto_groups
    UserInvite:
      type: object
      description: A user invite
      properties:
        id:
          description: Invite ID
          type: string
          example: d5p7eedra0h0lt6f59hg
        email:
          description: User's email address
          type: string
          example: user@example.com
        name:
          description: User's full name
          type: string
          example: John Doe
        role:
          description: User's NetBird account role
          type: string
          example: user
        auto_groups:
          description: Group IDs to auto-assign to peers registered by this user
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        expires_at:
          description: Invite expiration time
          type: string
          format: date-time
          example: "2024-01-25T10:00:00Z"
        created_at:
          description: Invite creation time
          type: string
          format: date-time
          example: "2024-01-22T10:00:00Z"
        expired:
          description: Whether the invite has expired
          type: boolean
          example: false
        invite_token:
          description: The invite link to be shared with the user. Only returned when the invite is created or regenerated.
          type: string
          example: nbi_Xk5Lz9mP2vQwRtYu1aN3bC4dE5fGh0ABC123
      required:
        - id
        - email
        - name
        - role
        - auto_groups
        - expires_at
        - created_at
        - expired
    UserInviteInfo:
      type: object
      description: Public information about an invite
      properties:
        email:
          description: User's email address
          type: string
          example: user@example.com
        name:
          description: User's full name
          type: string
          example: John Doe
        expires_at:
          description: Invite expiration time
          type: string
          format: date-time
          example: "2024-01-25T10:00:00Z"
        valid:
          description: Whether the invite is still valid (not expired)
          type: boolean
          example: true
        invited_by:
          description: Name of the user who sent the invite
          type: string
          example: Admin User
      required:
        - email
        - name
        - expires_at
        - valid
        - invited_by
    UserInviteAcceptRequest:
      type: object
      description: Request to accept an invite and set password
      properties:
        password:
          description: >-
            The password the user wants to set. Must be at least 8 characters long
            and contain at least one uppercase letter, one digit, and one special
            character (any character that is not a letter or digit, including spaces).
          type: string
          format: password
          minLength: 8
          pattern: '^(?=.*[0-9])(?=.*[A-Z])(?=.*[^a-zA-Z0-9]).{8,}$'
          example: SecurePass123!
      required:
        - password
    UserInviteAcceptResponse:
      type: object
      description: Response after accepting an invite
      properties:
        success:
          description: Whether the invite was accepted successfully
          type: boolean
          example: true
      required:
        - success
    UserInviteRegenerateRequest:
      type: object
      description: Request to regenerate an invite link
      properties:
        expires_in:
          description: Invite expiration time in seconds (default 72 hours)
          type: integer
          example: 259200
    UserInviteRegenerateResponse:
      type: object
      description: Response after regenerating an invite
      properties:
        invite_token:
          description: The new invite token
          type: string
          example: nbi_Xk5Lz9mP2vQwRtYu1aN3bC4dE5fGh0ABC123
        invite_expires_at:
          description: New invite expiration time
          type: string
          format: date-time
          example: "2024-01-28T10:00:00Z"
      required:
        - invite_token
        - invite_expires_at
    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
    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
    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
    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
    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
    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
    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
    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
    SetupKeyBase:
      type: object
      properties:
        id:
          description: Setup Key ID
          type: string
          example: 2531583362
        name:
          description: Setup key name identifier
          type: string
          example: Default key
        expires:
          description: Setup Key expiration date
          type: string
          format: date-time
          example: "2023-06-01T14:47:22.291057Z"
        type:
          description: Setup key type, one-off for single time usage and reusable
          type: string
          example: reusable
        valid:
          description: Setup key validity status
          type: boolean
          example: true
        revoked:
          description: Setup key revocation status
          type: boolean
          example: false
        used_times:
          description: Usage count of setup key
          type: integer
          example: 2
        last_used:
          description: Setup key last usage date
          type: string
          format: date-time
          example: "2023-05-05T09:00:35.477782Z"
        state:
          description: Setup key status, "valid", "overused","expired" or "revoked"
          type: string
          example: valid
        auto_groups:
          description: List of group IDs to auto-assign to peers registered with this key
          type: array
          items:
            type: string
            example: "ch8i4ug6lnn4g9hqv7m0"
        updated_at:
          description: Setup key last update date
          type: string
          format: date-time
          example: "2023-05-05T09:00:35.477782Z"
        usage_limit:
          description: A number of times this key can be used. The value of 0 indicates the unlimited usage.
          type: integer
          example: 0
        ephemeral:
          description: Indicate that the peer will be ephemeral or not
          type: boolean
          example: true
        allow_extra_dns_labels:
          description: Allow extra DNS labels to be added to the peer
          type: boolean
          example: true
      required:
        - id
        - key
        - name
        - expires
        - type
        - valid
        - revoked
        - used_times
        - last_used
        - state
        - auto_groups
        - updated_at
        - usage_limit
        - ephemeral
        - allow_extra_dns_labels
    SetupKeyClear:
      allOf:
        - $ref: '#/components/schemas/SetupKeyBase'
        - type: object
          properties:
            key:
              description: Setup Key as plain text
              type: string
              example: A616097E-FCF0-48FA-9354-CA4A61142761
          required:
            - key
    SetupKey:
      allOf:
        - $ref: '#/components/schemas/SetupKeyBase'
        - type: object
          properties:
            key:
              description: Setup Key as secret
              type: string
              example: A6160****
          required:
            - key
    SetupKeyRequest:
      type: object
      properties:
        revoked:
          description: Setup key revocation status
          type: boolean
          example: false
        auto_groups:
          description: List of group IDs to auto-assign to peers registered with this key
          type: array
          items:
            type: string
            example: "ch8i4ug6lnn4g9hqv7m0"
      required:
        - revoked
        - auto_groups
    CreateSetupKeyRequest:
      type: object
      properties:
        name:
          description: Setup Key name
          type: string
          example: Default key
        type:
          description: Setup key type, one-off for single time usage and reusable
          type: string
          example: reusable
        expires_in:
          description: Expiration time in seconds
          type: integer
          minimum: 86400
          maximum: 31536000
          example: 86400
        auto_groups:
          description: List of group IDs to auto-assign to peers registered with this key
          type: array
          items:
            type: string
            example: "ch8i4ug6lnn4g9hqv7m0"
        usage_limit:
          description: A number of times this key can be used. The value of 0 indicates the unlimited usage.
          type: integer
          example: 0
        ephemeral:
          description: Indicate that the peer will be ephemeral or not
          type: boolean
          example: true
        allow_extra_dns_labels:
          description: Allow extra DNS labels to be added to the peer
          type: boolean
          example: true
      required:
        - name
        - type
        - expires_in
        - auto_groups
        - usage_limit
    PersonalAccessToken:
      type: object
      properties:
        id:
          description: ID of a token
          type: string
          example: ch8i54g6lnn4g9hqv7n0
        name:
          description: Name of the token
          type: string
          example: My first token
        expiration_date:
          description: Date the token expires
          type: string
          format: date-time
          example: "2023-05-05T14:38:28.977616Z"
        created_by:
          description: User ID of the user who created the token
          type: string
          example: google-oauth2|277474792786460067937
        created_at:
          description: Date the token was created
          type: string
          format: date-time
          example: "2023-05-02T14:48:20.465209Z"
        last_used:
          description: Date the token was last used
          type: string
          format: date-time
          example: "2023-05-04T12:45:25.9723616Z"
      required:
        - id
        - name
        - expiration_date
        - created_by
        - created_at
    PersonalAccessTokenGenerated:
      type: object
      properties:
        plain_token:
          description: Plain text representation of the generated token
          type: string
          example: 2023-05-02T14:48:20.465209Z
        personal_access_token:
          $ref: '#/components/schemas/PersonalAccessToken'
      required:
        - plain_token
        - personal_access_token
    PersonalAccessTokenRequest:
      type: object
      properties:
        name:
          description: Name of the token
          type: string
          example: My first token
        expires_in:
          description: Expiration in days
          type: integer
          minimum: 1
          maximum: 365
          example: 30
      required:
        - name
        - expires_in
    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
    GroupRequest:
      type: object
      properties:
        name:
          type: string
          description: Group name identifier
          example: devs
        peers:
          type: array
          description: List of peers ids
          items:
            type: string
            example: "ch8i4ug6lnn4g9hqv7m1"
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
      required:
        - name
    Group:
      allOf:
        - $ref: '#/components/schemas/GroupMinimum'
        - type: object
          properties:
            peers:
              description: List of peers object
              type: array
              items:
                $ref: '#/components/schemas/PeerMinimum'
            resources:
              type: array
              items:
                $ref: '#/components/schemas/Resource'
          required:
            - peers
            - resources
    PolicyRuleMinimum:
      type: object
      properties:
        name:
          description: Policy rule name identifier
          type: string
          example: Default
        description:
          description: Policy rule friendly description
          type: string
          example: This is a default rule that allows connections between all the resources
        enabled:
          description: Policy rule status
          type: boolean
          example: true
        action:
          description: Policy rule accept or drops packets
          type: string
          enum: ["accept","drop"]
          example: "accept"
        bidirectional:
          description: Define if the rule is applicable in both directions, sources, and destinations.
          type: boolean
          example: true
        protocol:
          description: Policy rule type of the traffic
          type: string
          enum: ["all", "tcp", "udp", "icmp", "netbird-ssh"]
          example: "tcp"
        ports:
          description: Policy rule affected ports
          type: array
          items:
            type: string
            example: "80"
        port_ranges:
          description: Policy rule affected ports ranges list
          type: array
          items:
            $ref: '#/components/schemas/RulePortRange'
        authorized_groups:
          description: Map of user group ids to a list of local users
          type: object
          additionalProperties:
            type: array
            items:
              type: string
              example: "group1"
      required:
        - name
        - enabled
        - bidirectional
        - protocol
        - action

    RulePortRange:
      description: Policy rule affected ports range
      type: object
      properties:
        start:
          description: The starting port of the range
          type: integer
          example: 80
        end:
          description: The ending port of the range
          type: integer
          example: 320
      required:
        - start
        - end

    PolicyRuleUpdate:
      allOf:
        - $ref: '#/components/schemas/PolicyRuleMinimum'
        - type: object
          properties:
            id:
              description: Policy rule ID
              type: string
              example: ch8i4ug6lnn4g9hqv7mg
            sources:
              description: Policy rule source group IDs
              type: array
              items:
                type: string
                example: "ch8i4ug6lnn4g9hqv797"
            sourceResource:
              description: Policy rule source resource that the rule is applied to
              $ref: '#/components/schemas/Resource'
            destinations:
              description: Policy rule destination group IDs
              type: array
              items:
                type: string
                example: "ch8i4ug6lnn4g9h7v7m0"
            destinationResource:
              description: Policy rule destination resource that the rule is applied to
              $ref: '#/components/schemas/Resource'

    PolicyRuleCreate:
      allOf:
        - $ref: '#/components/schemas/PolicyRuleMinimum'
        - type: object
          properties:
            sources:
              description: Policy rule source group IDs
              type: array
              items:
                type: string
                example: "ch8i4ug6lnn4g9hqv797"
            sourceResource:
              description: Policy rule source resource that the rule is applied to
              $ref: '#/components/schemas/Resource'
            destinations:
              description: Policy rule destination group IDs
              type: array
              items:
                type: string
                example: "ch8i4ug6lnn4g9h7v7m0"
            destinationResource:
              description: Policy rule destination resource that the rule is applied to
              $ref: '#/components/schemas/Resource'
    PolicyRule:
      allOf:
        - $ref: '#/components/schemas/PolicyRuleMinimum'
        - type: object
          properties:
            id:
              description: Policy rule ID
              type: string
              example: ch8i4ug6lnn4g9hqv7mg
            sources:
              description: Policy rule source group IDs
              type: array
              items:
                $ref: '#/components/schemas/GroupMinimum'
            sourceResource:
              description: Policy rule source resource that the rule is applied to
              $ref: '#/components/schemas/Resource'
            destinations:
              description: Policy rule destination group IDs
              type: array
              items:
                $ref: '#/components/schemas/GroupMinimum'
            destinationResource:
              description: Policy rule destination resource that the rule is applied to
              $ref: '#/components/schemas/Resource'
    PolicyMinimum:
      type: object
      properties:
        name:
          description: Policy name identifier
          type: string
          example: ch8i4ug6lnn4g9hqv7mg
        description:
          description: Policy friendly description
          type: string
          example: This is a default policy that allows connections between all the resources
        enabled:
          description: Policy status
          type: boolean
          example: true
      required:
        - name
        - enabled
    PolicyUpdate:
      allOf:
        - $ref: '#/components/schemas/PolicyMinimum'
        - type: object
          properties:
            source_posture_checks:
              description: Posture checks ID's applied to policy source groups
              type: array
              items:
                type: string
                example: "chacdk86lnnboviihd70"
            rules:
              description: Policy rule object for policy UI editor
              type: array
              items:
                $ref: '#/components/schemas/PolicyRuleUpdate'
          required:
            - rules
    PolicyCreate:
      allOf:
        - $ref: '#/components/schemas/PolicyMinimum'
        - type: object
          properties:
            source_posture_checks:
              description: Posture checks ID's applied to policy source groups
              type: array
              items:
                type: string
                example: "chacdk86lnnboviihd70"
            rules:
              description: Policy rule object for policy UI editor
              type: array
              items:
                $ref: '#/components/schemas/PolicyRuleUpdate'
          required:
            - rules
    Policy:
      allOf:
        - $ref: '#/components/schemas/PolicyMinimum'
        - type: object
          properties:
            id:
              description: Policy ID
              type: string
              example: ch8i4ug6lnn4g9hqv7mg
            source_posture_checks:
              description: Posture checks ID's applied to policy source groups
              type: array
              items:
                type: string
                example: "chacdk86lnnboviihd70"
            rules:
              description: Policy rule object for policy UI editor
              type: array
              items:
                $ref: '#/components/schemas/PolicyRule'
          required:
            - rules
            - source_posture_checks
    PostureCheck:
      type: object
      properties:
        id:
          description: Posture check ID
          type: string
          example: ch8i4ug6lnn4g9hqv7mg
        name:
          description: Posture check unique name identifier
          type: string
          example: Default
        description:
          description: Posture check friendly description
          type: string
          example: This checks if the peer is running required NetBird's version
        checks:
          $ref: '#/components/schemas/Checks'
      required:
        - id
        - name
        - checks
    Checks:
      description: List of objects that perform the actual checks
      type: object
      properties:
        nb_version_check:
          $ref: '#/components/schemas/NBVersionCheck'
        os_version_check:
          $ref: '#/components/schemas/OSVersionCheck'
        geo_location_check:
          $ref: '#/components/schemas/GeoLocationCheck'
        peer_network_range_check:
          $ref: '#/components/schemas/PeerNetworkRangeCheck'
        process_check:
          $ref: '#/components/schemas/ProcessCheck'
    NBVersionCheck:
      description: Posture check for the version of NetBird
      type: object
      $ref: '#/components/schemas/MinVersionCheck'
    OSVersionCheck:
      description: Posture check for the version of operating system
      type: object
      properties:
        android:
          description: Minimum version of Android
          $ref: '#/components/schemas/MinVersionCheck'
        darwin:
          $ref: '#/components/schemas/MinVersionCheck'
        ios:
          description: Minimum version of iOS
          $ref: '#/components/schemas/MinVersionCheck'
        linux:
          description: Minimum Linux kernel version
          $ref: '#/components/schemas/MinKernelVersionCheck'
        windows:
          description: Minimum Windows kernel build version
          $ref: '#/components/schemas/MinKernelVersionCheck'
      example:
        android:
          min_version: "13"
        ios:
          min_version: "17.3.1"
        darwin:
          min_version: "14.2.1"
        linux:
          min_kernel_version: "5.3.3"
        windows:
          min_kernel_version: "10.0.1234"
    MinVersionCheck:
      description: Posture check for the version of operating system
      type: object
      properties:
        min_version:
          description: Minimum acceptable version
          type: string
          example: "14.3"
      required:
        - min_version
    MinKernelVersionCheck:
      description: Posture check with the kernel version
      type: object
      properties:
        min_kernel_version:
          description: Minimum acceptable version
          type: string
          example: "6.6.12"
      required:
        - min_kernel_version
    GeoLocationCheck:
      description: Posture check for geo location
      type: object
      properties:
        locations:
          description: List of geo locations to which the policy applies
          type: array
          items:
            $ref: '#/components/schemas/Location'
        action:
          description: Action to take upon policy match
          type: string
          enum: [ "allow", "deny" ]
          example: "allow"
      required:
        - locations
        - action
    PeerNetworkRangeCheck:
      description: Posture check for allow or deny access based on peer local network addresses
      type: object
      properties:
        ranges:
          description: List of peer network ranges in CIDR notation
          type: array
          items:
            type: string
          example: ["192.168.1.0/24", "10.0.0.0/8", "2001:db8:1234:1a00::/56"]
        action:
          description: Action to take upon policy match
          type: string
          enum: [ "allow", "deny" ]
          example: "allow"
      required:
        - ranges
        - action
    ProcessCheck:
      description: Posture Check for binaries exist and are running in the peer’s system
      type: object
      properties:
        processes:
          type: array
          items:
            $ref: '#/components/schemas/Process'
      required:
        - processes
    Process:
      description: Describes the operational activity within a peer's system.
      type: object
      properties:
        linux_path:
          description: Path to the process executable file in a Linux operating system
          type: string
          example: "/usr/local/bin/netbird"
        mac_path:
          description: Path to the process executable file in a Mac operating system
          type: string
          example: "/Applications/NetBird.app/Contents/MacOS/netbird"
        windows_path:
          description: Path to the process executable file in a Windows operating system
          type: string
          example: "C:\ProgramData\NetBird\netbird.exe"
    Location:
      description: Describe geographical location information
      type: object
      properties:
        country_code:
          $ref: '#/components/schemas/CountryCode'
        city_name:
          $ref: '#/components/schemas/CityName'
      required:
        - country_code
    CountryCode:
      description: 2-letter ISO 3166-1 alpha-2 code that represents the country
      type: string
      example: "DE"
    CityName:
      description: Commonly used English name of the city
      type: string
      example: "Berlin"
    Country:
      description: Describe country geographical location information
      type: object
      properties:
        country_name:
          description: Commonly used English name of the country
          type: string
          example: "Germany"
        country_code:
          $ref: '#/components/schemas/CountryCode'
      required:
        - country_name
        - country_code
    City:
      description: Describe city geographical location information
      type: object
      properties:
        geoname_id:
          description: Integer ID of the record in GeoNames database
          type: integer
          example: 2950158
        city_name:
          description: Commonly used English name of the city
          type: string
          example: "Berlin"
      required:
        - geoname_id
        - city_name
    PostureCheckUpdate:
      type: object
      properties:
        name:
          description: Posture check name identifier
          type: string
          example: Default
        description:
          description: Posture check friendly description
          type: string
          example: This checks if the peer is running required NetBird's version
        checks:
          $ref: '#/components/schemas/Checks'
      required:
        - name
        - description
    RouteRequest:
      type: object
      properties:
        description:
          description: Route description
          type: string
          example: My first route
        network_id:
          description: Route network identifier, to group HA routes
          type: string
          maxLength: 40
          minLength: 1
          example: Route 1
        enabled:
          description: Route status
          type: boolean
          example: true
        peer:
          description: Peer Identifier associated with route. This property can not be set together with `peer_groups`
          type: string
          example: chacbco6lnnbn6cg5s91
        peer_groups:
          description: Peers Group Identifier associated with route. This property can not be set together with `peer`
          type: array
          items:
            type: string
            example: chacbco6lnnbn6cg5s91
        network:
          description: Network range in CIDR format, Conflicts with domains
          type: string
          example: 10.64.0.0/24
        domains:
          description: Domain list to be dynamically resolved. Max of 32 domains can be added per route configuration. Conflicts with network
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 32
            example: "example.com"
        metric:
          description: Route metric number. Lowest number has higher priority
          type: integer
          maximum: 9999
          minimum: 1
          example: 9999
        masquerade:
          description: Indicate if peer should masquerade traffic to this route's prefix
          type: boolean
          example: true
        groups:
          description: Group IDs containing routing peers
          type: array
          items:
            type: string
            example: "chacdk86lnnboviihd70"
        keep_route:
          description: Indicate if the route should be kept after a domain doesn't resolve that IP anymore
          type: boolean
          example: true
        access_control_groups:
          description: Access control group identifier associated with route.
          type: array
          items:
            type: string
            example: "chacbco6lnnbn6cg5s91"
        skip_auto_apply:
          description: Indicate if this exit node route (0.0.0.0/0) should skip auto-application for client routing
          type: boolean
          example: false
      required:
        - id
        - description
        - network_id
        - enabled
        # Only one property has to be set
        #- peer
        #- peer_groups
        # Only one property has to be set
        #- network
        #- domains
        - metric
        - masquerade
        - groups
        - keep_route
    Route:
      allOf:
        - type: object
          properties:
            id:
              description: Route Id
              type: string
              example: chacdk86lnnboviihd7g
            network_type:
              description: Network type indicating if it is a domain route or a IPv4/IPv6 route
              type: string
              example: IPv4
          required:
            - id
            - network_type
        - $ref: '#/components/schemas/RouteRequest'
    Resource:
      type: object
      properties:
        id:
          description: ID of the resource
          type: string
          example: chacdk86lnnboviihd7g
        type:
          description: Type of the resource
          $ref: '#/components/schemas/ResourceType'
      required:
        - id
        - type
    ResourceType:
      allOf:
        - $ref: '#/components/schemas/NetworkResourceType'
        - type: string
          enum: ["peer"]
          example: peer
    NetworkRequest:
      type: object
      properties:
        name:
          description: Network name
          type: string
          example: Remote Network 1
        description:
          description: Network description
          type: string
          example: A remote network that needs to be accessed
      required:
        - name
    Network:
      allOf:
        - type: object
          properties:
            id:
              description: Network ID
              type: string
              example: chacdk86lnnboviihd7g
            routers:
              description: List of router IDs associated with the network
              type: array
              items:
                type: string
                example: ch8i4ug6lnn4g9hqv7m0
            routing_peers_count:
              description: Count of routing peers associated with the network
              type: integer
              example: 2
            resources:
              description: List of network resource IDs associated with the network
              type: array
              items:
                type: string
                example: ch8i4ug6lnn4g9hqv7m1
            policies:
              description: List of policy IDs associated with the network
              type: array
              items:
                type: string
                example: ch8i4ug6lnn4g9hqv7m2
          required:
            - id
            - routers
            - resources
            - routing_peers_count
            - policies
        - $ref: '#/components/schemas/NetworkRequest'
    NetworkResourceMinimum:
      type: object
      properties:
        name:
          description: Network resource name
          type: string
          example: Remote Resource 1
        description:
          description: Network resource description
          type: string
          example: A remote resource inside network 1
        address:
          description: Network resource address (either a direct host like 1.1.1.1 or 1.1.1.1/32, or a subnet like 192.168.178.0/24, or domains like example.com and *.example.com)
          type: string
          example: "1.1.1.1"
        enabled:
          description: Network resource status
          type: boolean
          example: true
      required:
        - name
        - address
        - enabled
    NetworkResourceRequest:
      allOf:
        - $ref: '#/components/schemas/NetworkResourceMinimum'
        - type: object
          properties:
            groups:
              description: Group IDs containing the resource
              type: array
              items:
                type: string
                example: "chacdk86lnnboviihd70"
          required:
            - groups
            - address
    NetworkResource:
      allOf:
        - type: object
          properties:
            id:
              description: Network Resource ID
              type: string
              example: chacdk86lnnboviihd7g
            type:
              $ref: '#/components/schemas/NetworkResourceType'
            groups:
              description: Groups that the resource belongs to
              type: array
              items:
                $ref: '#/components/schemas/GroupMinimum'
          required:
            - id
            - type
            - groups
        - $ref: '#/components/schemas/NetworkResourceMinimum'
    NetworkResourceType:
      description: Network resource type based of the address
      type: string
      enum: [ "host", "subnet", "domain" ]
      example: host
    NetworkRouterRequest:
      type: object
      properties:
        peer:
          description: Peer Identifier associated with route. This property can not be set together with `peer_groups`
          type: string
          example: chacbco6lnnbn6cg5s91
        peer_groups:
          description: Peers Group Identifier associated with route. This property can not be set together with `peer`
          type: array
          items:
            type: string
            example: chacbco6lnnbn6cg5s91
        metric:
          description: Route metric number. Lowest number has higher priority
          type: integer
          maximum: 9999
          minimum: 1
          example: 9999
        masquerade:
          description: Indicate if peer should masquerade traffic to this route's prefix
          type: boolean
          example: true
        enabled:
          description: Network router status
          type: boolean
          example: true
      required:
        # Only one property has to be set
        #- peer
        #- peer_groups
        - metric
        - masquerade
        - enabled
    NetworkRouter:
      allOf:
        - type: object
          properties:
            id:
              description: Network Router Id
              type: string
              example: chacdk86lnnboviihd7g
          required:
            - id
        - $ref: '#/components/schemas/NetworkRouterRequest'
    Nameserver:
      type: object
      properties:
        ip:
          description: Nameserver IP
          type: string
          example: 8.8.8.8
        ns_type:
          description: Nameserver Type
          type: string
          enum: [ "udp" ]
          example: udp
        port:
          description: Nameserver Port
          type: integer
          example: 53
      required:
        - ip
        - ns_type
        - port
    NameserverGroupRequest:
      type: object
      properties:
        name:
          description: Name of nameserver group name
          type: string
          maxLength: 40
          minLength: 1
          example: Google DNS
        description:
          description: Description of the nameserver group
          type: string
          example: Google DNS servers
        nameservers:
          description: Nameserver list
          minLength: 1
          maxLength: 3
          type: array
          items:
            $ref: '#/components/schemas/Nameserver'
        enabled:
          description: Nameserver group status
          type: boolean
          example: true
        groups:
          description: Distribution group IDs that defines group of peers that will use this nameserver group
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        primary:
          description: Defines if a nameserver group is primary that resolves all domains. It should be true only if domains list is empty.
          type: boolean
          example: true
        domains:
          description: Match domain list. It should be empty only if primary is true.
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 255
            example: "example.com"
        search_domains_enabled:
          description: Search domain status for match domains. It should be true only if domains list is not empty.
          type: boolean
          example: true
      required:
        - name
        - description
        - nameservers
        - enabled
        - groups
        - primary
        - domains
        - search_domains_enabled
    NameserverGroup:
      allOf:
        - type: object
          properties:
            id:
              description: Nameserver group ID
              type: string
              example: ch8i4ug6lnn4g9hqv7m0
          required:
            - id
        - $ref: '#/components/schemas/NameserverGroupRequest'
    DNSSettings:
      type: object
      properties:
        disabled_management_groups:
          description: Groups whose DNS management is disabled
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
      required:
        - disabled_management_groups
    ZoneRequest:
      type: object
      properties:
        name:
          description: Zone name identifier
          type: string
          maxLength: 255
          minLength: 1
          example: Office Zone
        domain:
          description: Zone domain (FQDN)
          type: string
          example: example.com
        enabled:
          description: Zone status
          type: boolean
          default: true
        enable_search_domain:
          description: Enable this zone as a search domain
          type: boolean
          example: false
        distribution_groups:
          description: Group IDs that defines groups of peers that will resolve this zone
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
      required:
        - name
        - domain
        - enable_search_domain
        - distribution_groups
    Zone:
      allOf:
        - type: object
          properties:
            id:
              description: Zone ID
              type: string
              example: ch8i4ug6lnn4g9hqv7m0
            records:
              description: DNS records associated with this zone
              type: array
              items:
                $ref: '#/components/schemas/DNSRecord'
          required:
            - id
            - enabled
            - records
        - $ref: '#/components/schemas/ZoneRequest'
    DNSRecordType:
      type: string
      description: DNS record type
      enum:
        - A
        - AAAA
        - CNAME
      example: A
    DNSRecordRequest:
      type: object
      properties:
        name:
          description: FQDN for the DNS record. Must be a subdomain within or match the zone's domain.
          type: string
          example: www.example.com
        type:
          $ref: '#/components/schemas/DNSRecordType'
        content:
          description: DNS record content (IP address for A/AAAA, domain for CNAME)
          type: string
          maxLength: 255
          minLength: 1
          example: 192.168.1.1
        ttl:
          description: Time to live in seconds
          type: integer
          minimum: 0
          example: 300
      required:
        - name
        - type
        - content
        - ttl
    DNSRecord:
      allOf:
        - type: object
          properties:
            id:
              description: DNS record ID
              type: string
              example: ch8i4ug6lnn4g9hqv7m0
          required:
            - id
        - $ref: '#/components/schemas/DNSRecordRequest'
    Event:
      type: object
      properties:
        id:
          description: Event unique identifier
          type: string
          example: 10
        timestamp:
          description: The date and time when the event occurred
          type: string
          format: date-time
          example: "2023-05-05T10:04:37.473542Z"
        activity:
          description: The activity that occurred during the event
          type: string
          example: Route created
        activity_code:
          description: The string code of the activity that occurred during the event
          type: string
          enum: [
            "peer.user.add", "peer.setupkey.add", "user.join", "user.invite", "account.create", "account.delete",
            "user.peer.delete", "rule.add", "rule.update", "rule.delete",
            "policy.add", "policy.update", "policy.delete",
            "setupkey.add", "setupkey.update", "setupkey.revoke", "setupkey.overuse", "setupkey.delete",
            "group.add", "group.update", "group.delete",
            "peer.group.add", "peer.group.delete",
            "user.group.add", "user.group.delete", "user.role.update",
            "setupkey.group.add", "setupkey.group.delete",
            "dns.setting.disabled.management.group.add", "dns.setting.disabled.management.group.delete",
            "route.add", "route.delete", "route.update",
            "peer.ssh.enable", "peer.ssh.disable", "peer.rename",
            "peer.login.expiration.enable", "peer.login.expiration.disable",
            "nameserver.group.add", "nameserver.group.delete", "nameserver.group.update",
            "account.setting.peer.login.expiration.update", "account.setting.peer.login.expiration.enable", "account.setting.peer.login.expiration.disable",
            "personal.access.token.create", "personal.access.token.delete",
            "service.user.create", "service.user.delete",
            "user.block", "user.unblock", "user.delete",
            "user.peer.login", "peer.login.expire",
            "dashboard.login",
            "integration.create", "integration.update", "integration.delete",
            "account.setting.peer.approval.enable", "account.setting.peer.approval.disable",
            "peer.approve", "peer.approval.revoke",
            "transferred.owner.role",
            "posture.check.create", "posture.check.update", "posture.check.delete",
            "peer.inactivity.expiration.enable", "peer.inactivity.expiration.disable",
            "account.peer.inactivity.expiration.enable", "account.peer.inactivity.expiration.disable", "account.peer.inactivity.expiration.update",
            "account.setting.group.propagation.enable", "account.setting.group.propagation.disable",
            "account.setting.routing.peer.dns.resolution.enable", "account.setting.routing.peer.dns.resolution.disable",
            "network.create", "network.update", "network.delete",
            "network.resource.create", "network.resource.update", "network.resource.delete",
            "network.router.create", "network.router.update", "network.router.delete",
            "resource.group.add", "resource.group.delete",
            "account.dns.domain.update",
            "account.setting.lazy.connection.enable", "account.setting.lazy.connection.disable",
            "account.network.range.update",
            "peer.ip.update",
            "user.approve", "user.reject", "user.create",
            "account.settings.auto.version.update",
            "identityprovider.create", "identityprovider.update", "identityprovider.delete",
            "dns.zone.create", "dns.zone.update", "dns.zone.delete",
            "dns.zone.record.create", "dns.zone.record.update", "dns.zone.record.delete",
            "peer.job.create",
            "user.password.change",
            "user.invite.link.create", "user.invite.link.accept", "user.invite.link.regenerate", "user.invite.link.delete",
            "service.create", "service.update", "service.delete"
          ]
          example: route.add
        initiator_id:
          description: The ID of the initiator of the event. E.g., an ID of a user that triggered the event.
          type: string
          example: google-oauth2|123456789012345678901
        initiator_name:
          description: The name of the initiator of the event.
          type: string
          example: John Doe
        initiator_email:
          description: The e-mail address of the initiator of the event. E.g., an e-mail of a user that triggered the event.
          type: string
          example: demo@netbird.io
        target_id:
          description: The ID of the target of the event. E.g., an ID of the peer that a user removed.
          type: string
          example: chad9d86lnnc59g18ou0
        meta:
          description: The metadata of the event
          type: object
          additionalProperties:
            type: string
          example: { "name": "my route", "network_range": "10.64.0.0/24", "peer_id": "chacbco6lnnbn6cg5s91"}
      required:
        - id
        - timestamp
        - activity
        - activity_code
        - initiator_id
        - initiator_name
        - initiator_email
        - target_id
        - meta
    IngressPeerCreateRequest:
      type: object
      properties:
        peer_id:
          description: ID of the peer that is used as an ingress peer
          type: string
          example: ch8i4ug6lnn4g9hqv7m0
        enabled:
          description: Defines if an ingress peer is enabled
          type: boolean
          example: true
        fallback:
          description: Defines if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
          type: boolean
          example: true
      required:
        - peer_id
        - enabled
        - fallback
    IngressPeerUpdateRequest:
      type: object
      properties:
        enabled:
          description: Defines if an ingress peer is enabled
          type: boolean
          example: true
        fallback:
          description: Defines if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
          type: boolean
          example: true
      required:
        - enabled
        - fallback
    IngressPeer:
      type: object
      properties:
        id:
          description: ID of the ingress peer
          type: string
          example: ch8i4ug6lnn4g9hqv7m0
        peer_id:
          description: ID of the peer that is used as an ingress peer
          type: string
          example: x7p3kqf2rdd8j5zxw4n9
        ingress_ip:
          description: Ingress IP address of the ingress peer where the traffic arrives
          type: string
          example: 192.34.0.123
        available_ports:
          $ref: '#/components/schemas/AvailablePorts'
        enabled:
          description: Indicates if an ingress peer is enabled
          type: boolean
          example: true
        connected:
          description: Indicates if an ingress peer is connected to the management server
          type: boolean
          example: true
        fallback:
          description: Indicates if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
          type: boolean
          example: true
        region:
          description: Region of the ingress peer
          type: string
          example: germany
      required:
        - id
        - peer_id
        - ingress_ip
        - available_ports
        - enabled
        - connected
        - fallback
        - region
    AvailablePorts:
      type: object
      properties:
        tcp:
          description: Number of available TCP  ports left on the ingress peer
          type: integer
          example: 45765
        udp:
          description: Number of available UDP ports left on the ingress peer
          type: integer
          example: 50000
      required:
        - tcp
        - udp
    IngressPortAllocationRequest:
      type: object
      properties:
        name:
          description: Name of the ingress port allocation
          type: string
          example: Ingress Port Allocation 1
        enabled:
          description: Indicates if an ingress port allocation is enabled
          type: boolean
          example: true
        port_ranges:
          description: List of port ranges that are forwarded by the ingress peer
          type: array
          items:
            $ref: '#/components/schemas/IngressPortAllocationRequestPortRange'
        direct_port:
          description: Direct port allocation
          $ref: '#/components/schemas/IngressPortAllocationRequestDirectPort'
      required:
        - name
        - enabled
    IngressPortAllocationRequestPortRange:
      type: object
      properties:
        start:
          description: The starting port of the range of forwarded ports
          type: integer
          example: 80
        end:
          description: The ending port of the range of forwarded ports
          type: integer
          example: 320
        protocol:
          description: The protocol accepted by the port range
          type: string
          enum: [ "tcp", "udp", "tcp/udp" ]
          example: tcp
      required:
        - start
        - end
        - protocol
    IngressPortAllocationRequestDirectPort:
      type: object
      properties:
        count:
          description: The number of ports to be forwarded
          type: integer
          example: 5
        protocol:
          description: The protocol accepted by the port
          type: string
          enum: [ "tcp", "udp", "tcp/udp" ]
          example: udp
      required:
        - count
        - protocol
    IngressPortAllocation:
      type: object
      properties:
        id:
          description: ID of the ingress port allocation
          type: string
          example: ch8i4ug6lnn4g9hqv7m0
        name:
          description: Name of the ingress port allocation
          type: string
          example: Ingress Peer Allocation 1
        ingress_peer_id:
          description: ID of the ingress peer that forwards the ports
          type: string
          example: x7p3kqf2rdd8j5zxw4n9
        region:
          description: Region of the ingress peer
          type: string
          example: germany
        enabled:
          description: Indicates if an ingress port allocation is enabled
          type: boolean
          example: true
        ingress_ip:
          description: Ingress IP address of the ingress peer where the traffic arrives
          type: string
          example: 192.34.0.123
        port_range_mappings:
          description: List of port ranges that are allowed to be used by the ingress peer
          type: array
          items:
            $ref: '#/components/schemas/IngressPortAllocationPortMapping'
      required:
        - id
        - name
        - ingress_peer_id
        - region
        - enabled
        - ingress_ip
        - port_range_mappings
    IngressPortAllocationPortMapping:
      type: object
      properties:
        translated_start:
          description: The starting port of the translated range of forwarded ports
          type: integer
          example: 80
        translated_end:
          description: The ending port of the translated range of forwarded ports
          type: integer
          example: 320
        ingress_start:
          description: The starting port of the range of ingress ports mapped to the forwarded ports
          type: integer
          example: 1080
        ingress_end:
          description: The ending port of the range of ingress ports mapped to the forwarded ports
          type: integer
          example: 1320
        protocol:
          description: Protocol accepted by the ports
          type: string
          enum: [ "tcp", "udp", "tcp/udp" ]
          example: tcp
      required:
        - translated_start
        - translated_end
        - ingress_start
        - ingress_end
        - protocol
    NetworkTrafficLocation:
      type: object
      properties:
        city_name:
          type: string
          description: "Name of the city (if known)."
          example: "Berlin"
        country_code:
          type: string
          description: "ISO country code (if known)."
          example: "DE"
      required:
        - city_name
        - country_code
    NetworkTrafficEndpoint:
      type: object
      properties:
        id:
          type: string
          description: "ID of this endpoint (e.g., peer ID or resource ID)."
          example: "ch8i4ug6lnn4g9hqv7m0"
        type:
          type: string
          description: "Type of the endpoint object (e.g., UNKNOWN, PEER, HOST_RESOURCE)."
          example: "PEER"
        name:
          type: string
          description: "Name is the name of the endpoint object (e.g., a peer name)."
          example: "My Peer"
        geo_location:
          $ref: '#/components/schemas/NetworkTrafficLocation'
        os:
          type: string
          nullable: true
          description: "Operating system of the peer, if applicable."
          example: "Linux"
        address:
          type: string
          description: "IP address (and possibly port) in string form."
          example: "100.64.0.10:51820"
        dns_label:
          type: string
          nullable: true
          description: "DNS label/name if available."
          example: "*.mydomain.com"
      required:
        - id
        - type
        - name
        - geo_location
        - os
        - address
        - dns_label
    NetworkTrafficUser:
      type: object
      properties:
        id:
          type: string
          description: "UserID is the ID of the user that initiated the event (can be empty as not every event is user-initiated)."
          example: "google-oauth2|123456789012345678901"
        email:
          type: string
          description: "Email of the user who initiated the event (if any)."
          example: "alice@netbird.io"
        name:
            type: string
            description: "Name of the user who initiated the event (if any)."
            example: "Alice Smith"
      required:
        - id
        - email
        - name
    NetworkTrafficPolicy:
      type: object
      properties:
        id:
          type: string
          description: "ID of the policy that allowed this event."
          example: "ch8i4ug6lnn4g9hqv7m0"
        name:
          type: string
          description: "Name of the policy that allowed this event."
          example: "All to All"
      required:
        - id
        - name
    NetworkTrafficICMP:
      type: object
      properties:
        type:
          type: integer
          description: "ICMP type (if applicable)."
          example: 8
        code:
          type: integer
          description: "ICMP code (if applicable)."
          example: 0
      required:
        - type
        - code
    NetworkTrafficSubEvent:
      type: object
      properties:
        type:
          type: string
          description: Type of the event (e.g., TYPE_UNKNOWN, TYPE_START, TYPE_END, TYPE_DROP).
          example: TYPE_START
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the event as sent by the peer.
          example: 2025-03-20T16:23:58.125397Z
      required:
        - type
        - timestamp
    NetworkTrafficEvent:
      type: object
      properties:
        flow_id:
          type: string
          description: "FlowID is the ID of the connection flow. Not unique because it can be the same for multiple events (e.g., start and end of the connection)."
          example: "61092452-b17c-4b14-b7cf-a2158c549826"
        reporter_id:
          type: string
          description: "ID of the reporter of the event (e.g., the peer that reported the event)."
          example: "ch8i4ug6lnn4g9hqv7m0"
        source:
          $ref: '#/components/schemas/NetworkTrafficEndpoint'
        destination:
          $ref: '#/components/schemas/NetworkTrafficEndpoint'
        user:
          $ref: '#/components/schemas/NetworkTrafficUser'
        policy:
          $ref: '#/components/schemas/NetworkTrafficPolicy'
        icmp:
          $ref: '#/components/schemas/NetworkTrafficICMP'
        protocol:
          type: integer
          description: "Protocol is the protocol of the traffic (e.g. 1 = ICMP, 6 = TCP, 17 = UDP, etc.)."
          example: 6
        direction:
          type: string
          description: "Direction of the traffic (e.g. DIRECTION_UNKNOWN, INGRESS, EGRESS)."
          example: "INGRESS"
        rx_bytes:
          type: integer
          description: "Number of bytes received."
          example: 1234
        rx_packets:
          type: integer
          description: "Number of packets received."
          example: 5
        tx_bytes:
          type: integer
          description: "Number of bytes transmitted."
          example: 1234
        tx_packets:
          type: integer
          description: "Number of packets transmitted."
          example: 5
        events:
          type: array
          description: "List of events that are correlated to this flow (e.g., start, end)."
          items:
            $ref: '#/components/schemas/NetworkTrafficSubEvent'
      required:
        - id
        - flow_id
        - reporter_id
        - receive_timestamp
        - source
        - destination
        - user
        - policy
        - icmp
        - protocol
        - direction
        - rx_bytes
        - rx_packets
        - tx_bytes
        - tx_packets
        - events
    NetworkTrafficEventsResponse:
      type: object
      properties:
        data:
          type: array
          description: List of network traffic events
          items:
            $ref: "#/components/schemas/NetworkTrafficEvent"
        page:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of items per page
        total_records:
          type: integer
          description: Total number of event records available
        total_pages:
          type: integer
          description: Total number of pages available
      required:
        - data
        - page
        - page_size
        - total_records
        - total_pages
    ProxyAccessLog:
      type: object
      properties:
        id:
          type: string
          description: "Unique identifier for the access log entry"
          example: "ch8i4ug6lnn4g9hqv7m0"
        proxy_id:
          type: string
          description: "ID of the reverse proxy that handled the request"
          example: "ch8i4ug6lnn4g9hqv7m0"
        timestamp:
          type: string
          format: date-time
          description: "Timestamp when the request was made"
          example: "2024-01-31T15:30:00Z"
        method:
          type: string
          description: "HTTP method of the request"
          example: "GET"
        host:
          type: string
          description: "Host header of the request"
          example: "example.com"
        path:
          type: string
          description: "Path of the request"
          example: "/api/users"
        duration_ms:
          type: integer
          description: "Duration of the request in milliseconds"
          example: 150
        status_code:
          type: integer
          description: "HTTP status code returned"
          example: 200
        source_ip:
          type: string
          description: "Source IP address of the request"
          example: "192.168.1.100"
        reason:
          type: string
          description: "Reason for the request result (e.g., authentication failure)"
          example: "Authentication failed"
        user_id:
          type: string
          description: "ID of the authenticated user, if applicable"
          example: "user-123"
        auth_method_used:
          type: string
          description: "Authentication method used (e.g., password, pin, oidc)"
          example: "oidc"
        country_code:
          type: string
          description: "Country code from geolocation"
          example: "US"
        city_name:
          type: string
          description: "City name from geolocation"
          example: "San Francisco"
      required:
        - id
        - proxy_id
        - timestamp
        - method
        - host
        - path
        - duration_ms
        - status_code
    ProxyAccessLogsResponse:
      type: object
      properties:
        data:
          type: array
          description: List of proxy access log entries
          items:
            $ref: "#/components/schemas/ProxyAccessLog"
        page:
          type: integer
          description: Current page number
          example: 1
        page_size:
          type: integer
          description: Number of items per page
          example: 50
        total_records:
          type: integer
          description: Total number of log records available
          example: 523
        total_pages:
          type: integer
          description: Total number of pages available
          example: 11
      required:
        - data
        - page
        - page_size
        - total_records
        - total_pages
    IdentityProviderType:
      type: string
      description: Type of identity provider
      enum:
        - oidc
        - zitadel
        - entra
        - google
        - okta
        - pocketid
        - microsoft
      example: oidc
    IdentityProvider:
      type: object
      properties:
        id:
          description: Identity provider ID
          type: string
          example: ch8i4ug6lnn4g9hqv7l0
        type:
          $ref: '#/components/schemas/IdentityProviderType'
        name:
          description: Human-readable name for the identity provider
          type: string
          example: My OIDC Provider
        issuer:
          description: OIDC issuer URL
          type: string
          example: https://accounts.google.com
        client_id:
          description: OAuth2 client ID
          type: string
          example: 123456789.apps.googleusercontent.com
      required:
        - type
        - name
        - issuer
        - client_id
    IdentityProviderRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/IdentityProviderType'
        name:
          description: Human-readable name for the identity provider
          type: string
          example: My OIDC Provider
        issuer:
          description: OIDC issuer URL
          type: string
          example: https://accounts.google.com
        client_id:
          description: OAuth2 client ID
          type: string
          example: 123456789.apps.googleusercontent.com
        client_secret:
          description: OAuth2 client secret
          type: string
          example: secret123
      required:
        - type
        - name
        - issuer
        - client_id
        - client_secret
    ReverseProxy:
      type: object
      properties:
        id:
          type: string
          description: Reverse proxy ID
        name:
          type: string
          description: Reverse proxy name
        domain:
          type: string
          description: Domain for the reverse proxy
        proxy_cluster:
          type: string
          description: The proxy cluster handling this reverse proxy (derived from domain)
          example: "eu.proxy.netbird.io"
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ReverseProxyTarget'
          description: List of target backends for this reverse proxy
        enabled:
          type: boolean
          description: Whether the reverse proxy is enabled
        pass_host_header:
          type: boolean
          description: When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
        rewrite_redirects:
          type: boolean
          description: When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
        auth:
          $ref: '#/components/schemas/ReverseProxyAuthConfig'
        meta:
          $ref: '#/components/schemas/ReverseProxyMeta'
      required:
        - id
        - name
        - domain
        - targets
        - enabled
        - auth
        - meta
    ReverseProxyMeta:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          description: Timestamp when the reverse proxy was created
          example: "2024-02-03T10:30:00Z"
        certificate_issued_at:
          type: string
          format: date-time
          description: Timestamp when the certificate was issued (empty if not yet issued)
          example: "2024-02-03T10:35:00Z"
        status:
          type: string
          enum:
            - pending
            - active
            - tunnel_not_created
            - certificate_pending
            - certificate_failed
            - error
          description: Current status of the reverse proxy
          example: "active"
      required:
        - created_at
        - status
    ReverseProxyRequest:
      type: object
      properties:
        name:
          type: string
          description: Reverse proxy name
        domain:
          type: string
          description: Domain for the reverse proxy
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ReverseProxyTarget'
          description: List of target backends for this reverse proxy
        enabled:
          type: boolean
          description: Whether the reverse proxy is enabled
          default: true
        pass_host_header:
          type: boolean
          description: When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
        rewrite_redirects:
          type: boolean
          description: When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
        auth:
          $ref: '#/components/schemas/ReverseProxyAuthConfig'
      required:
        - name
        - domain
        - targets
        - auth
        - enabled
    ReverseProxyTarget:
      type: object
      properties:
        target_id:
          type: string
          description: Target ID
        target_type:
          type: string
          description: Target type (e.g., "peer", "resource")
          enum: [peer, resource]
        path:
          type: string
          description: URL path prefix for this target
        protocol:
          type: string
          description: Protocol to use when connecting to the backend
          enum: [http, https]
        host:
          type: string
          description: Backend ip or domain for this target
        port:
          type: integer
          description: Backend port for this target. Use 0 or omit to use the scheme default (80 for http, 443 for https).
        enabled:
          type: boolean
          description: Whether this target is enabled
      required:
        - target_id
        - target_type
        - protocol
        - port
        - enabled
    ReverseProxyAuthConfig:
      type: object
      properties:
        password_auth:
          $ref: '#/components/schemas/PasswordAuthConfig'
        pin_auth:
          $ref: '#/components/schemas/PINAuthConfig'
        bearer_auth:
          $ref: '#/components/schemas/BearerAuthConfig'
        link_auth:
          $ref: '#/components/schemas/LinkAuthConfig'
    PasswordAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether password auth is enabled
        password:
          type: string
          description: Auth password
      required:
        - enabled
        - password
    PINAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether PIN auth is enabled
        pin:
          type: string
          description: PIN value
      required:
        - enabled
        - pin
    BearerAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether bearer auth is enabled
        distribution_groups:
          type: array
          items:
            type: string
          description: List of group IDs that can use bearer auth
      required:
        - enabled
    LinkAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether link auth is enabled
      required:
        - enabled
    ProxyCluster:
      type: object
      description: A proxy cluster represents a group of proxy nodes serving the same address
      properties:
        address:
          type: string
          description: Cluster address used for CNAME targets
          example: "eu.proxy.netbird.io"
        connected_proxies:
          type: integer
          description: Number of proxy nodes connected in this cluster
          example: 3
      required:
        - address
        - connected_proxies
    ReverseProxyDomainType:
      type: string
      description: Type of Reverse Proxy Domain
      enum:
        - free
        - custom
      example: free
    ReverseProxyDomain:
      type: object
      properties:
        id:
          type: string
          description: Domain ID
        domain:
          type: string
          description: Domain name
        validated:
          type: boolean
          description: Whether the domain has been validated
        type:
          $ref: '#/components/schemas/ReverseProxyDomainType'
        target_cluster:
          type: string
          description: The proxy cluster this domain is validated against (only for custom domains)
      required:
        - id
        - domain
        - validated
        - type
    ReverseProxyDomainRequest:
      type: object
      properties:
        domain:
          type: string
          description: Domain name
        target_cluster:
          type: string
          description: The proxy cluster this domain should be validated against
      required:
        - domain
        - target_cluster
    InstanceStatus:
      type: object
      description: Instance status information
      properties:
        setup_required:
          description: Indicates whether the instance requires initial setup
          type: boolean
          example: true
      required:
        - setup_required
    SetupRequest:
      type: object
      description: Request to set up the initial admin user
      properties:
        email:
          description: Email address for the admin user
          type: string
          example: admin@example.com
        password:
          description: Password for the admin user (minimum 8 characters)
          type: string
          format: password
          minLength: 8
          example: securepassword123
        name:
          description: Display name for the admin user (defaults to email if not provided)
          type: string
          example: Admin User
      required:
        - email
        - password
        - name
    SetupResponse:
      type: object
      description: Response after successful instance setup
      properties:
        user_id:
          description: The ID of the created user
          type: string
          example: abc123def456
        email:
          description: Email address of the created user
          type: string
          example: admin@example.com
      required:
        - user_id
        - email
    InstanceVersionInfo:
      type: object
      description: Version information for NetBird components
      properties:
        management_current_version:
          description: The current running version of the management server
          type: string
          example: "0.35.0"
        dashboard_available_version:
          description: The latest available version of the dashboard (from GitHub releases)
          type: string
          example: "2.10.0"
        management_available_version:
          description: The latest available version of the management server (from GitHub releases)
          type: string
          example: "0.35.0"
        management_update_available:
          description: Indicates if a newer management version is available
          type: boolean
          example: true
      required:
        - management_current_version
        - management_update_available
  responses:
    not_found:
      description: Resource not found
      content: { }
    validation_failed_simple:
      description: Validation failed
      content: { }
    bad_request:
      description: Bad Request
      content: { }
    internal_error:
      description: Internal Server Error
      content: { }
    validation_failed:
      description: Validation failed
      content: { }
    forbidden:
      description: Forbidden
      content: { }
    requires_authentication:
      description: Requires authentication
      content: { }
  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.....".
security:
  - BearerAuth: [ ]
  - TokenAuth: [ ]
paths:
  /api/instance:
    get:
      summary: Get Instance Status
      description: Returns the instance status including whether initial setup is required. This endpoint does not require authentication.
      tags: [ Instance ]
      security: [ ]
      responses:
        '200':
          description: Instance status information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceStatus'
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/instance/version:
    get:
      summary: Get Version Info
      description: Returns version information for NetBird components including the current management server version and latest available versions from GitHub.
      tags: [ Instance ]
      security:
        - BearerAuth: []
        - TokenAuth: []
      responses:
        '200':
          description: Version information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceVersionInfo'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/setup:
    post:
      summary: Setup Instance
      description: Creates the initial admin user for the instance. This endpoint does not require authentication but only works when setup is required (no accounts exist and embedded IDP is enabled).
      tags: [ Instance ]
      security: [ ]
      requestBody:
        description: Initial admin user details
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SetupRequest'
      responses:
        '200':
          description: Setup completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '412':
          description: Setup already completed
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/peers/{peerId}/jobs:
    get:
      summary: List Jobs
      description: Retrieve all jobs for a given peer
      tags: [ Jobs ]
      security:
        - BearerAuth: []
        - TokenAuth: []
      parameters:
        - in: path
          name: peerId
          description: The unique identifier of a peer
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobResponse'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/internal_error'
    post:
      summary: Create Job
      description: Create a new job for a given peer
      tags: [ Jobs ]
      security:
        - BearerAuth: []
        - TokenAuth: []
      parameters:
        - in: path
          name: peerId
          description: The unique identifier of a peer
          required: true
          schema:
            type: string
      requestBody:
        description: Create job request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobRequest'
        required: true
      responses:
        '201':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '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}/jobs/{jobId}:
    get:
      summary: Get Job
      description: Retrieve details of a specific job
      tags: [ Jobs ]
      security:
        - BearerAuth: []
        - TokenAuth: []
      parameters:
        - in: path
          name: peerId
          required: true
          description: The unique identifier of a peer
          schema:
            type: string
        - in: path
          name: jobId
          required: true
          description: The unique identifier of a job
          schema:
            type: string
      responses:
        '200':
          description: A Job object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/accounts:
    get:
      summary: List all Accounts
      description: Returns a list of accounts of a user. Always returns a list of one account.
      tags: [ Accounts ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON array of accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/accounts/{accountId}:
    delete:
      summary: Delete an Account
      description: Deletes an account and all its resources. Only account owners can delete accounts.
      tags: [ Accounts ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: accountId
          required: true
          schema:
            type: string
          description: The unique identifier of an account
      responses:
        '200':
          description: Delete account 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"
    put:
      summary: Update an Account
      description: Update information about an account
      tags: [ Accounts ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: accountId
          required: true
          schema:
            type: string
          description: The unique identifier of an account
      requestBody:
        description: update an account
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/AccountRequest'
      responses:
        '200':
          description: An Account object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users:
    get:
      summary: List all Users
      description: Returns a list of all users
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: query
          name: service_user
          schema:
            type: boolean
          description: Filters users and returns either regular users or service users
      responses:
        '200':
          description: A JSON array of Users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a User
      description: Creates a new service user or sends an invite to a regular user
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: User invite information
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/UserCreateRequest'
      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/{userId}:
    put:
      summary: Update a User
      description: Update information about a User
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      requestBody:
        description: User update
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/UserRequest'
      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '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 User
      description: This method removes a user from accessing the system. For this leaves the IDP user intact unless the `--user-delete-from-idp` is passed to management startup.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      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/users/{userId}/tokens:
    get:
      summary: List all Tokens
      description: Returns a list of all tokens for a user
      tags: [ Tokens ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      responses:
        '200':
          description: A JSON Array of PersonalAccessTokens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PersonalAccessToken'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Token
      description: Create a new token for a user
      tags: [ Tokens ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      requestBody:
        description: PersonalAccessToken create parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonalAccessTokenRequest'
      responses:
        '200':
          description: The token in plain text
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalAccessTokenGenerated'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/{userId}/tokens/{tokenId}:
    get:
      summary: Retrieve a Token
      description: Returns a specific token for a user
      tags: [ Tokens ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
        - in: path
          name: tokenId
          required: true
          schema:
            type: string
          description: The unique identifier of a token
      responses:
        '200':
          description: A PersonalAccessTokens Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalAccessToken'
        '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 Token
      description: Delete a token for a user
      tags: [ Tokens ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
        - in: path
          name: tokenId
          required: true
          schema:
            type: string
          description: The unique identifier of a token
      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/users/{userId}/invite:
    post:
      summary: Resend user invitation
      description: Resend user invitation
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      responses:
        '200':
          description: Invite 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/users/{userId}/approve:
    post:
      summary: Approve user
      description: Approve a user that is pending approval
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      responses:
        '200':
          description: Returns the approved user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/User"
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/{userId}/reject:
    delete:
      summary: Reject user
      description: Reject a user that is pending approval by removing them from the account
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      responses:
        '200':
          description: User rejected successfully
          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/users/{userId}/password:
    put:
      summary: Change user password
      description: Change the password for a user. Only available when embedded IdP is enabled. Users can only change their own password.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      requestBody:
        description: Password change request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChangeRequest'
      responses:
        '200':
          description: Password changed successfully
          content: {}
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '412':
          description: Precondition failed - embedded IdP is not enabled
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/current:
    get:
      summary: Retrieve current user
      description: Get information about the current user
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/invites:
    get:
      summary: List user invites
      description: Lists all pending invites for the account. Only available when embedded IdP is enabled.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: List of invites
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserInvite'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '412':
          description: Precondition failed - embedded IdP is not enabled
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a user invite
      description: Creates an invite link for a new user. Only available when embedded IdP is enabled. The user is not created until they accept the invite.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: User invite information
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInviteCreateRequest'
      responses:
        '200':
          description: Invite created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInvite'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '409':
          description: User or invite already exists
          content: { }
        '412':
          description: Precondition failed - embedded IdP is not enabled
          content: { }
        '422':
          "$ref": "#/components/responses/validation_failed"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/invites/{inviteId}:
    delete:
      summary: Delete a user invite
      description: Deletes a pending invite. Only available when embedded IdP is enabled.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: inviteId
          required: true
          schema:
            type: string
          description: The ID of the invite to delete
      responses:
        '200':
          description: Invite deleted successfully
          content: { }
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          description: Invite not found
          content: { }
        '412':
          description: Precondition failed - embedded IdP is not enabled
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/invites/{inviteId}/regenerate:
    post:
      summary: Regenerate a user invite
      description: Regenerates an invite link for an existing invite. Invalidates the previous token and creates a new one.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: inviteId
          required: true
          schema:
            type: string
          description: The ID of the invite to regenerate
      requestBody:
        description: Regenerate options
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInviteRegenerateRequest'
      responses:
        '200':
          description: Invite regenerated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInviteRegenerateResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          description: Invite not found
          content: { }
        '412':
          description: Precondition failed - embedded IdP is not enabled
          content: { }
        '422':
          "$ref": "#/components/responses/validation_failed"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/invites/{token}:
    get:
      summary: Get invite information
      description: Retrieves public information about an invite. This endpoint is unauthenticated and protected by the token itself.
      tags: [ Users ]
      security: []
      parameters:
        - in: path
          name: token
          required: true
          schema:
            type: string
          description: The invite token
      responses:
        '200':
          description: Invite information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInviteInfo'
        '400':
          "$ref": "#/components/responses/bad_request"
        '404':
          description: Invite not found or invalid token
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/invites/{token}/accept:
    post:
      summary: Accept an invite
      description: Accepts an invite and creates the user with the provided password. This endpoint is unauthenticated and protected by the token itself.
      tags: [ Users ]
      security: []
      parameters:
        - in: path
          name: token
          required: true
          schema:
            type: string
          description: The invite token
      requestBody:
        description: Password to set for the new user
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInviteAcceptRequest'
      responses:
        '200':
          description: Invite accepted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInviteAcceptResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '404':
          description: Invite not found or invalid token
          content: { }
        '412':
          description: Precondition failed - embedded IdP is not enabled or invite expired
          content: { }
        '422':
          "$ref": "#/components/responses/validation_failed"
        '500':
          "$ref": "#/components/responses/internal_error"
  /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"
  /api/peers/{peerId}/ingress/ports:
    get:
      x-cloud-only: true
      summary: List all Port Allocations
      description: Returns a list of all ingress port allocations for a peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
        - in: query
          name: name
          schema:
            type: string
          description: Filters ingress port allocations by name
      responses:
        '200':
          description: A JSON Array of Ingress Port Allocations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IngressPortAllocation'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      x-cloud-only: true
      summary: Create a Port Allocation
      description: Creates a new ingress port allocation for a peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
      requestBody:
        description: New Ingress Port Allocation request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IngressPortAllocationRequest'
      responses:
        '200':
          description: A Ingress Port Allocation object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPortAllocation'
        '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}/ingress/ports/{allocationId}:
    get:
      x-cloud-only: true
      summary: Retrieve a Port Allocation
      description: Get information about an ingress port allocation
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
        - in: path
          name: allocationId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress port allocation
      responses:
        '200':
          description: A Ingress Port Allocation object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPortAllocation'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      x-cloud-only: true
      summary: Update a Port Allocation
      description: Update information about an ingress port allocation
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
        - in: path
          name: allocationId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress port allocation
      requestBody:
        description: update an ingress port allocation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngressPortAllocationRequest'
      responses:
        '200':
          description: A Ingress Port Allocation object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPortAllocation'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      x-cloud-only: true
      summary: Delete a Port Allocation
      description: Delete an ingress port allocation
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
        - in: path
          name: allocationId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress port allocation
      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/ingress/peers:
    get:
      x-cloud-only: true
      summary: List all Ingress Peers
      description: Returns a list of all ingress peers
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Ingress Peers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IngressPeer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      x-cloud-only: true
      summary: Create a Ingress Peer
      description: Creates a new ingress peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Ingress Peer request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IngressPeerCreateRequest'
      responses:
        '200':
          description: A Ingress Peer object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPeer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/ingress/peers/{ingressPeerId}:
    get:
      x-cloud-only: true
      summary: Retrieve a Ingress Peer
      description: Get information about an ingress peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: ingressPeerId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress peer
      responses:
        '200':
          description: A Ingress Peer object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPeer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      x-cloud-only: true
      summary: Update a Ingress Peer
      description: Update information about an ingress peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: ingressPeerId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress peer
      requestBody:
        description: update an ingress peer
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IngressPeerUpdateRequest'
      responses:
        '200':
          description: A Ingress Peer object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPeer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      x-cloud-only: true
      summary: Delete a Ingress Peer
      description: Delete an ingress peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: ingressPeerId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress 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/setup-keys:
    get:
      summary: List all Setup Keys
      description: Returns a list of all Setup Keys
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Setup keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SetupKey'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Setup Key
      description: Creates a setup key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Setup Key request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/CreateSetupKeyRequest'
      responses:
        '200':
          description: A Setup Keys Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupKeyClear'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/setup-keys/{keyId}:
    get:
      summary: Retrieve a Setup Key
      description: Get information about a setup key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: keyId
          required: true
          schema:
            type: string
          description: The unique identifier of a setup key
      responses:
        '200':
          description: A Setup Key object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupKey'
        '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 Setup Key
      description: Update information about a setup key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: keyId
          required: true
          schema:
            type: string
          description: The unique identifier of a setup key
      requestBody:
        description: update to Setup Key
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SetupKeyRequest'
      responses:
        '200':
          description: A Setup Key object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupKey'
        '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 Setup Key
      description: Delete a Setup Key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: keyId
          required: true
          schema:
            type: string
          description: The unique identifier of a setup key
      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/groups:
    get:
      summary: List all Groups
      description: Returns a list of all groups
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: query
          name: name
          required: false
          schema:
            type: string
          description: Filter groups by name (exact match)
          example: "devs"
      responses:
        '200':
          description: A JSON Array of Groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '404':
          "$ref": "#/components/responses/not_found"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Group
      description: Creates a group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Group request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/GroupRequest'
      responses:
        '200':
          description: A Group Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/groups/{groupId}:
    get:
      summary: Retrieve a Group
      description: Get information about a group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: groupId
          required: true
          schema:
            type: string
          description: The unique identifier of a group
      responses:
        '200':
          description: A Group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '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 Group
      description: Update/Replace a group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: groupId
          required: true
          schema:
            type: string
          description: The unique identifier of a group
      requestBody:
        description: Update Group request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/GroupRequest'
      responses:
        '200':
          description: A Group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '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 Group
      description: Delete a group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: groupId
          required: true
          schema:
            type: string
          description: The unique identifier of a group
      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/policies:
    get:
      summary: List all Policies
      description: Returns a list of all policies
      tags: [ Policies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Policies
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Policy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Policy
      description: Creates a policy
      tags: [ Policies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Policy request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/PolicyUpdate'
      responses:
        '200':
          description: A Policy Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
  /api/policies/{policyId}:
    get:
      summary: Retrieve a Policy
      description: Get information about a Policies
      tags: [ Policies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: policyId
          required: true
          schema:
            type: string
          description: The unique identifier of a policy
      responses:
        '200':
          description: A Policy object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '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 Policy
      description: Update/Replace a Policy
      tags: [ Policies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: policyId
          required: true
          schema:
            type: string
          description: The unique identifier of a policy
      requestBody:
        description: Update Policy request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/PolicyCreate'
      responses:
        '200':
          description: A Policy object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '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 Policy
      description: Delete a policy
      tags: [ Policies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: policyId
          required: true
          schema:
            type: string
          description: The unique identifier of a policy
      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/routes:
    get:
      summary: List all Routes
      description: Returns a list of all routes
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Routes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Route'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Route
      description: Creates a Route
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Routes request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/RouteRequest'
      responses:
        '200':
          description: A Route Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/routes/{routeId}:
    get:
      summary: Retrieve a Route
      description: Get information about a Routes
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: routeId
          required: true
          schema:
            type: string
          description: The unique identifier of a route
      responses:
        '200':
          description: A Route object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        '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 Route
      description: Update/Replace a Route
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: routeId
          required: true
          schema:
            type: string
          description: The unique identifier of a route
      requestBody:
        description: Update Route request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteRequest'
      responses:
        '200':
          description: A Route object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        '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 Route
      description: Delete a route
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: routeId
          required: true
          schema:
            type: string
          description: The unique identifier of a route
      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/networks:
    get:
      summary: List all Networks
      description: Returns a list of all networks
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Networks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Network'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Network
      description: Creates a Network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Network request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NetworkRequest'
      responses:
        '200':
          description: A Network Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/networks/{networkId}:
    get:
      summary: Retrieve a Network
      description: Get information about a Network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      responses:
        '200':
          description: A Network object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
        '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 Network
      description: Update/Replace a Network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      requestBody:
        description: Update Network request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetworkRequest'
      responses:
        '200':
          description: A Network object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
        '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 Network
      description: Delete a network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      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/networks/{networkId}/resources:
    get:
      summary: List all Network Resources
      description: Returns a list of all resources in a network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      responses:
        '200':
          description: A JSON Array of Resources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkResource'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Network Resource
      description: Creates a Network Resource
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      requestBody:
        description: New Network Resource request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NetworkResourceRequest'
      responses:
        '200':
          description: A Network Resource Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkResource'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/networks/{networkId}/resources/{resourceId}:
    get:
      summary: Retrieve a Network Resource
      description: Get information about a Network Resource
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
          description: The unique identifier of a network resource
      responses:
        '200':
          description: A Network Resource object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkResource'
        '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 Network Resource
      description: Update a Network Resource
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
          description: The unique identifier of a resource
      requestBody:
        description: Update Network Resource request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NetworkResourceRequest'
      responses:
        '200':
          description: A Network Resource object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkResource'
        '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 Network Resource
      description: Delete a network resource
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
            description: The unique identifier of a network
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
            description: The unique identifier of a network resource
      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/networks/{networkId}/routers:
    get:
      summary: List all Network Routers
      description: Returns a list of all routers in a network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      responses:
        '200':
          description: A JSON Array of Routers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkRouter'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Network Router
      description: Creates a Network Router
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      requestBody:
        description: New Network Router request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NetworkRouterRequest'
      responses:
        '200':
          description: A Router Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkRouter'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/networks/{networkId}/routers/{routerId}:
    get:
      summary: Retrieve a Network Router
      description: Get information about a Network Router
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
        - in: path
          name: routerId
          required: true
          schema:
            type: string
          description: The unique identifier of a router
      responses:
        '200':
          description: A Router object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkRouter'
        '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 Network Router
      description: Update a Network Router
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
        - in: path
          name: routerId
          required: true
          schema:
            type: string
          description: The unique identifier of a router
      requestBody:
        description: Update Network Router request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NetworkRouterRequest'
      responses:
        '200':
          description: A Router object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkRouter'
        '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 Network Router
      description: Delete a network router
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
            description: The unique identifier of a network
        - in: path
          name: routerId
          required: true
          schema:
            type: string
            description: The unique identifier of a router
      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/networks/routers:
    get:
      summary: List all Network Routers
      description: Returns a list of all routers in a network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Routers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkRouter'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/nameservers:
    get:
      summary: List all Nameserver Groups
      description: Returns a list of all Nameserver Groups
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Nameserver Groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NameserverGroup'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Nameserver Group
      description: Creates a Nameserver Group
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Nameserver Groups request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NameserverGroupRequest'
      responses:
        '200':
          description: A Nameserver Groups Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameserverGroup'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/nameservers/{nsgroupId}:
    get:
      summary: Retrieve a Nameserver Group
      description: Get information about a Nameserver Groups
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: nsgroupId
          required: true
          schema:
            type: string
          description: The unique identifier of a Nameserver Group
      responses:
        '200':
          description: A Nameserver Group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameserverGroup'
        '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 Nameserver Group
      description: Update/Replace a Nameserver Group
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: nsgroupId
          required: true
          schema:
            type: string
          description: The unique identifier of a Nameserver Group
      requestBody:
        description: Update Nameserver Group request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NameserverGroupRequest'
      responses:
        '200':
          description: A Nameserver Group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameserverGroup'
        '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 Nameserver Group
      description: Delete a Nameserver Group
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: nsgroupId
          required: true
          schema:
            type: string
          description: The unique identifier of a Nameserver Group
      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/dns/settings:
    get:
      summary: Retrieve DNS settings
      description: Returns a DNS settings object
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Object of DNS Setting
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DNSSettings'
        '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 DNS Settings
      description: Updates a DNS settings object
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: A DNS settings object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/DNSSettings'
      responses:
        '200':
          description: A JSON Object of DNS Setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSSettings'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/zones:
    get:
      summary: List all DNS Zones
      description: Returns a list of all custom DNS zones
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of DNS Zones
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Zone'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a DNS Zone
      description: Creates a new custom DNS zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: A DNS zone object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ZoneRequest'
      responses:
        '200':
          description: A JSON Object of the created DNS Zone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/zones/{zoneId}:
    get:
      summary: Retrieve a DNS Zone
      description: Returns information about a specific DNS zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
      responses:
        '200':
          description: A JSON Object of a DNS Zone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a DNS Zone
      description: Updates a custom DNS zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
      requestBody:
        description: A DNS zone object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ZoneRequest'
      responses:
        '200':
          description: A JSON Object of the updated DNS Zone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a DNS Zone
      description: Deletes a custom DNS zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
      responses:
        '200':
          description: Zone deletion successful
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/zones/{zoneId}/records:
    get:
      summary: List all DNS Records
      description: Returns a list of all DNS records in a zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
      responses:
        '200':
          description: A JSON Array of DNS Records
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DNSRecord'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a DNS Record
      description: Creates a new DNS record in a zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
      requestBody:
        description: A DNS record object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/DNSRecordRequest'
      responses:
        '200':
          description: A JSON Object of the created DNS Record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSRecord'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/zones/{zoneId}/records/{recordId}:
    get:
      summary: Retrieve a DNS Record
      description: Returns information about a specific DNS record
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
        - in: path
          name: recordId
          required: true
          schema:
            type: string
          description: The unique identifier of a DNS record
          example: chacbco6lnnbn6cg5s92
      responses:
        '200':
          description: A JSON Object of a DNS Record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSRecord'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a DNS Record
      description: Updates a DNS record in a zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
        - in: path
          name: recordId
          required: true
          schema:
            type: string
          description: The unique identifier of a DNS record
          example: chacbco6lnnbn6cg5s92
      requestBody:
        description: A DNS record object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/DNSRecordRequest'
      responses:
        '200':
          description: A JSON Object of the updated DNS Record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSRecord'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a DNS Record
      description: Deletes a DNS record from a zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
        - in: path
          name: recordId
          required: true
          schema:
            type: string
          description: The unique identifier of a DNS record
          example: chacbco6lnnbn6cg5s92
      responses:
        '200':
          description: Record deletion successful
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/events/audit:
    get:
      summary: List all Audit Events
      description: Returns a list of all audit events
      tags: [ Events ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/events/network-traffic:
    get:
      summary: List all Traffic Events
      description: Returns a list of all network traffic events
      tags: [ Events ]
      x-cloud-only: true
      x-experimental: true
      parameters:
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50000
            default: 1000
        - name: user_id
          in: query
          description: Filter by user ID
          required: false
          schema:
            type: string
        - name: reporter_id
          in: query
          description: Filter by reporter ID
          required: false
          schema:
            type: string
        - name: protocol
          in: query
          description: Filter by protocol
          required: false
          schema:
            type: integer
        - name: type
          in: query
          description: Filter by event type
          required: false
          schema:
            type: string
            enum: [TYPE_UNKNOWN, TYPE_START, TYPE_END, TYPE_DROP]
        - name: connection_type
          in: query
          description: Filter by connection type
          required: false
          schema:
            type: string
            enum: [P2P, ROUTED]
        - name: direction
          in: query
          description: Filter by direction
          required: false
          schema:
            type: string
            enum: [INGRESS, EGRESS, DIRECTION_UNKNOWN]
        - name: search
          in: query
          description: Case-insensitive partial match on user email, source/destination names, and source/destination addresses
          required: false
          schema:
            type: string
        - name: start_date
          in: query
          description: Start date for filtering events (ISO 8601 format, e.g., 2024-01-01T00:00:00Z).
          required: false
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          description: End date for filtering events (ISO 8601 format, e.g., 2024-01-31T23:59:59Z).
          required: false
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: List of network traffic events
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NetworkTrafficEventsResponse"
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/events/proxy:
    get:
      summary: List all Reverse Proxy Access Logs
      description: Returns a paginated list of all reverse proxy access log entries
      tags: [ Events ]
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number for pagination (1-indexed)
        - in: query
          name: page_size
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
          description: Number of items per page (max 100)
        - in: query
          name: search
          schema:
            type: string
          description: General search across host, path, source IP, user email, and user name
        - in: query
          name: source_ip
          schema:
            type: string
          description: Filter by source IP address
        - in: query
          name: host
          schema:
            type: string
          description: Filter by host header
        - in: query
          name: path
          schema:
            type: string
          description: Filter by request path (supports partial matching)
        - in: query
          name: user_id
          schema:
            type: string
          description: Filter by authenticated user ID
        - in: query
          name: user_email
          schema:
            type: string
          description: Filter by user email (partial matching)
        - in: query
          name: user_name
          schema:
            type: string
          description: Filter by user name (partial matching)
        - in: query
          name: method
          schema:
            type: string
            enum: [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS]
          description: Filter by HTTP method
        - in: query
          name: status
          schema:
            type: string
            enum: [success, failed]
          description: Filter by status (success = 2xx/3xx, failed = 1xx/4xx/5xx)
        - in: query
          name: status_code
          schema:
            type: integer
            minimum: 100
            maximum: 599
          description: Filter by HTTP status code
        - in: query
          name: start_date
          schema:
            type: string
            format: date-time
          description: Filter by timestamp >= start_date (RFC3339 format)
        - in: query
          name: end_date
          schema:
            type: string
            format: date-time
          description: Filter by timestamp <= end_date (RFC3339 format)
      responses:
        "200":
          description: Paginated list of reverse proxy access logs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProxyAccessLogsResponse"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/posture-checks:
    get:
      summary: List all Posture Checks
      description: Returns a list of all posture checks
      tags: [ "Posture Checks" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of posture checks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PostureCheck'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Posture Check
      description: Creates a posture check
      tags: [ "Posture Checks" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New posture check request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/PostureCheckUpdate'
      responses:
        '200':
          description: A posture check Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
  /api/posture-checks/{postureCheckId}:
    get:
      summary: Retrieve a Posture Check
      description: Get information about a posture check
      tags: [ "Posture Checks" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: postureCheckId
          required: true
          schema:
            type: string
          description: The unique identifier of a posture check
      responses:
        '200':
          description: A posture check object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
        '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 Posture Check
      description: Update/Replace a posture check
      tags: [ "Posture Checks" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: postureCheckId
          required: true
          schema:
            type: string
          description: The unique identifier of a posture check
      requestBody:
        description: Update Rule request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/PostureCheckUpdate'
      responses:
        '200':
          description: A posture check object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
        '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 Posture Check
      description: Delete a posture check
      tags: [ "Posture Checks" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: postureCheckId
          required: true
          schema:
            type: string
          description: The unique identifier of a posture check
      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/locations/countries:
    get:
      summary: List all country codes
      description: Get list of all country in 2-letter ISO 3166-1 alpha-2 codes
      tags: [ "Geo Locations" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: List of country codes
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: "DE"
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/locations/countries/{country}/cities:
    get:
      summary: List all city names by country
      description: Get a list of all English city names for a given country code
      tags: [ "Geo Locations" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: country
          required: true
          schema:
            $ref: '#/components/schemas/Country'
      responses:
        '200':
          description: List of city names
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/City'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/identity-providers:
    get:
      summary: List all Identity Providers
      description: Returns a list of all identity providers configured for the account
      tags: [ Identity Providers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON array of identity providers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdentityProvider'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create an Identity Provider
      description: Creates a new identity provider configuration
      tags: [ Identity Providers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: Identity provider configuration
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IdentityProviderRequest'
      responses:
        '200':
          description: An Identity Provider object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/identity-providers/{idpId}:
    get:
      summary: Retrieve an Identity Provider
      description: Get information about a specific identity provider
      tags: [ Identity Providers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: idpId
          required: true
          schema:
            type: string
          description: The unique identifier of an identity provider
      responses:
        '200':
          description: An Identity Provider object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '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 an Identity Provider
      description: Update an existing identity provider configuration
      tags: [ Identity Providers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: idpId
          required: true
          schema:
            type: string
          description: The unique identifier of an identity provider
      requestBody:
        description: Identity provider update
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IdentityProviderRequest'
      responses:
        '200':
          description: An Identity Provider object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '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 an Identity Provider
      description: Delete an identity provider configuration
      tags: [ Identity Providers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: idpId
          required: true
          schema:
            type: string
          description: The unique identifier of an identity provider
      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/reverse-proxies:
    get:
      summary: List all Reverse Proxies
      description: Returns a list of all reverse proxies
      tags: [ Reverse Proxy ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of reverse proxies
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReverseProxy'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Reverse Proxy
      description: Creates a new reverse proxy
      tags: [ Reverse Proxy ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New reverse proxy request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReverseProxyRequest'
      responses:
        '200':
          description: Reverse proxy created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReverseProxy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/clusters:
    get:
      summary: List available proxy clusters
      description: Returns a list of available proxy clusters with their connection status
      tags: [ Reverse Proxy ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of proxy clusters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProxyCluster'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/{proxyId}:
    get:
      summary: Retrieve a Reverse Proxy
      description: Get information about a specific reverse proxy
      tags: [ Reverse Proxy ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: proxyId
          required: true
          schema:
            type: string
          description: The unique identifier of a reverse proxy
      responses:
        '200':
          description: A reverse proxy object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReverseProxy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Reverse Proxy
      description: Update an existing reverse proxy
      tags: [ Reverse Proxy ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: proxyId
          required: true
          schema:
            type: string
          description: The unique identifier of a reverse proxy
      requestBody:
        description: Reverse proxy update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReverseProxyRequest'
      responses:
        '200':
          description: Reverse proxy updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReverseProxy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Reverse Proxy
      description: Delete an existing reverse proxy
      tags: [ Reverse Proxy ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: proxyId
          required: true
          schema:
            type: string
          description: The unique identifier of a reverse proxy
      responses:
        '200':
          description: Reverse proxy deleted
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/domains:
    get:
      summary: Retrieve Reverse Proxy Domains
      description: Get information about domains that can be used for Reverse Proxy endpoints.
      tags: [ Reverse Proxy ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of ReverseProxyDomains
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReverseProxyDomain'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Custom domain
      description: Create a new Custom domain for use with Reverse Proxy endpoints, this will trigger an initial validation check
      tags: [ Reverse Proxy ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: Custom domain creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReverseProxyDomainRequest'
      responses:
        '200':
          description: Reverse proxy created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReverseProxy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/domains/{domainId}:
    delete:
      summary: Delete a Custom domain
      description: Delete an existing reverse proxy custom domain
      tags: [ Reverse Proxy ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: domainId
          required: true
          schema:
            type: string
          description: The custom domain ID
      responses:
        '204':
          description: Reverse proxy custom domain deleted
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/domains/{domainId}/validate:
    get:
      summary: Validate a custom domain
      description: Trigger domain ownership validation for a custom domain
      tags: [ Reverse Proxy ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: domainId
          required: true
          schema:
            type: string
          description: The custom domain ID
      responses:
        '202':
          description: Reverse proxy custom domain validation triggered
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"