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: Services
    description: Interact with and view information about reverse proxy services.
  - 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

  - name: Usage
    description: Retrieve current usage statistics for the account.
    x-cloud-only: true
  - name: Subscription
    description: Manage and view information about account subscriptions.
    x-cloud-only: true
  - name: Plans
    description: Retrieve available plans and products.
    x-cloud-only: true
  - name: Checkout
    description: Manage checkout sessions for plan subscriptions.
    x-cloud-only: true
  - name: AWS Marketplace
    description: Manage AWS Marketplace subscriptions.
    x-cloud-only: true
  - name: Portal
    description: Access customer portal for subscription management.
    x-cloud-only: true
  - name: Invoice
    description: Manage and retrieve account invoices.
    x-cloud-only: true
  - name: MSP
    description: MSP portal for Tenant management.
    x-cloud-only: true
  - name: IDP
    description: Manage identity provider integrations for user and group sync.
    x-cloud-only: true
  - name: EDR Intune Integrations
    description: Manage Microsoft Intune EDR integrations.
    x-cloud-only: true
  - name: EDR SentinelOne Integrations
    description: Manage SentinelOne EDR integrations.
    x-cloud-only: true
  - name: EDR Falcon Integrations
    description: Manage CrowdStrike Falcon EDR integrations.
    x-cloud-only: true
  - name: EDR Huntress Integrations
    description: Manage Huntress EDR integrations.
    x-cloud-only: true
  - name: EDR Peers
    description: Manage EDR compliance bypass for peers.
    x-cloud-only: true
  - name: Event Streaming Integrations
    description: Manage event streaming integrations.
    x-cloud-only: true
  - name: Notifications
    description: Manage notification channels for account event alerts.
    x-cloud-only: 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
        peer_expose_enabled:
          description: Enables or disables peer expose. If enabled, peers can expose local services through the reverse proxy using the CLI.
          type: boolean
          example: false
        peer_expose_groups:
          description: Limits which peer groups are allowed to expose services. If empty, all peers are allowed when peer expose is enabled.
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        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"
        auto_update_always:
          description: When true, updates are installed automatically in the background. When false, updates require user interaction from the UI.
          type: boolean
          example: false
        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
        - peer_expose_enabled
        - peer_expose_groups
    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"
        service_id:
          type: string
          description: "ID of the service 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"
        subdivision_code:
          type: string
          description: "First-level administrative subdivision ISO code (e.g. state/province)"
          example: "CA"
        bytes_upload:
          type: integer
          format: int64
          description: "Bytes uploaded (request body size)"
          example: 1024
        bytes_download:
          type: integer
          format: int64
          description: "Bytes downloaded (response body size)"
          example: 8192
        protocol:
          type: string
          description: "Protocol type: http, tcp, or udp"
          example: "http"
      required:
        - id
        - service_id
        - timestamp
        - method
        - host
        - path
        - duration_ms
        - status_code
        - bytes_upload
        - bytes_download
    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
    Service:
      type: object
      properties:
        id:
          type: string
          description: Service ID
          example: "cs8i4ug6lnn4g9hqv7mg"
        name:
          type: string
          description: Service name
          example: "myapp.example.netbird.app"
        domain:
          type: string
          description: Domain for the service
          example: "myapp.example.netbird.app"
        mode:
          type: string
          description: Service mode. "http" for L7 reverse proxy, "tcp"/"udp"/"tls" for L4 passthrough.
          enum: [http, tcp, udp, tls]
          default: http
          example: "http"
        listen_port:
          type: integer
          minimum: 0
          maximum: 65535
          description: Port the proxy listens on (L4/TLS only)
          example: 8443
        port_auto_assigned:
          type: boolean
          description: Whether the listen port was auto-assigned
          readOnly: true
          example: false
        proxy_cluster:
          type: string
          description: The proxy cluster handling this service (derived from domain)
          example: "eu.proxy.netbird.io"
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ServiceTarget'
          description: List of target backends for this service
        enabled:
          type: boolean
          description: Whether the service is enabled
          example: true
        terminated:
          type: boolean
          description: Whether the service has been terminated. Terminated services cannot be updated. Services that violate the Terms of Service will be terminated.
          readOnly: true
          example: false
        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
          example: false
        rewrite_redirects:
          type: boolean
          description: When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
          example: false
        auth:
          $ref: '#/components/schemas/ServiceAuthConfig'
        access_restrictions:
          $ref: '#/components/schemas/AccessRestrictions'
        meta:
          $ref: '#/components/schemas/ServiceMeta'
      required:
        - id
        - name
        - domain
        - targets
        - enabled
        - auth
        - meta
    ServiceMeta:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          description: Timestamp when the service 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 service
          example: "active"
      required:
        - created_at
        - status
    ServiceRequest:
      type: object
      properties:
        name:
          type: string
          description: Service name
          example: "myapp.example.netbird.app"
        domain:
          type: string
          description: Domain for the service
          example: "myapp.example.netbird.app"
        mode:
          type: string
          description: Service mode. "http" for L7 reverse proxy, "tcp"/"udp"/"tls" for L4 passthrough.
          enum: [http, tcp, udp, tls]
          default: http
          example: "http"
        listen_port:
          type: integer
          minimum: 0
          maximum: 65535
          description: Port the proxy listens on (L4/TLS only). Set to 0 for auto-assignment.
          example: 5432
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ServiceTarget'
          description: List of target backends for this service
        enabled:
          type: boolean
          description: Whether the service is enabled
          default: true
          example: 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
          example: false
        rewrite_redirects:
          type: boolean
          description: When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
          example: false
        auth:
          $ref: '#/components/schemas/ServiceAuthConfig'
        access_restrictions:
          $ref: '#/components/schemas/AccessRestrictions'
      required:
        - name
        - domain
        - enabled
    ServiceTargetOptions:
      type: object
      properties:
        skip_tls_verify:
          type: boolean
          description: Skip TLS certificate verification for this backend
          example: false
        request_timeout:
          type: string
          description: Per-target response timeout as a Go duration string (e.g. "30s", "2m")
          example: "30s"
        path_rewrite:
          type: string
          description: Controls how the request path is rewritten before forwarding to the backend. Default strips the matched prefix. "preserve" keeps the full original request path.
          enum: [preserve]
          example: "preserve"
        custom_headers:
          type: object
          description: Extra headers sent to the backend. Hop-by-hop and proxy-managed headers (Host, Connection, Transfer-Encoding, etc.) are rejected.
          propertyNames:
            type: string
            pattern: '^[!#$%&''*+.^_`|~0-9A-Za-z-]+$'
          additionalProperties:
            type: string
            pattern: '^[^\r\n]*$'
          example: {"X-Custom-Header": "value"}
        proxy_protocol:
          type: boolean
          description: Send PROXY Protocol v2 header to this backend (TCP/TLS only)
          example: false
        session_idle_timeout:
          type: string
          description: Idle timeout before a UDP session is reaped, as a Go duration string (e.g. "30s", "2m").
          example: "2m"
    ServiceTarget:
      type: object
      properties:
        target_id:
          type: string
          description: Target ID
          example: "cs8i4ug6lnn4g9hqv7mg"
        target_type:
          type: string
          description: Target type
          enum: [peer, host, domain, subnet]
          example: "subnet"
        path:
          type: string
          description: URL path prefix for this target (HTTP only)
          example: "/"
        protocol:
          type: string
          description: Protocol to use when connecting to the backend
          enum: [http, https, tcp, udp]
          example: "http"
        host:
          type: string
          description: Backend ip or domain for this target
          example: "10.10.0.1"
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: Backend port for this target
          example: 8080
        enabled:
          type: boolean
          description: Whether this target is enabled
          example: true
        options:
          $ref: '#/components/schemas/ServiceTargetOptions'
      required:
        - target_id
        - target_type
        - protocol
        - port
        - enabled
    ServiceAuthConfig:
      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'
        header_auths:
          type: array
          items:
            $ref: '#/components/schemas/HeaderAuthConfig'
    HeaderAuthConfig:
      type: object
      description: Static header-value authentication. The proxy checks that the named header matches the configured value.
      properties:
        enabled:
          type: boolean
          description: Whether header auth is enabled
          example: true
        header:
          type: string
          description: HTTP header name to check (e.g. "Authorization", "X-API-Key")
          example: "X-API-Key"
        value:
          type: string
          description: Expected header value. For Basic auth use "Basic base64(user:pass)". For Bearer use "Bearer token". Cleared in responses.
          example: "my-secret-api-key"
      required:
        - enabled
        - header
        - value
    AccessRestrictions:
      type: object
      description: Connection-level access restrictions based on IP address or geography. Applies to both HTTP and L4 services.
      properties:
        allowed_cidrs:
          type: array
          items:
            type: string
            format: cidr
            example: "192.168.1.0/24"
          description: CIDR allowlist. If non-empty, only IPs matching these CIDRs are allowed.
        blocked_cidrs:
          type: array
          items:
            type: string
            format: cidr
            example: "10.0.0.0/8"
          description: CIDR blocklist. Connections from these CIDRs are rejected. Evaluated after allowed_cidrs.
        allowed_countries:
          type: array
          items:
            type: string
            pattern: '^[a-zA-Z]{2}$'
            example: "US"
          description: ISO 3166-1 alpha-2 country codes to allow. If non-empty, only these countries are permitted.
        blocked_countries:
          type: array
          items:
            type: string
            pattern: '^[a-zA-Z]{2}$'
            example: "DE"
          description: ISO 3166-1 alpha-2 country codes to block.
    PasswordAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether password auth is enabled
          example: true
        password:
          type: string
          description: Auth password
          example: "s3cret"
      required:
        - enabled
        - password
    PINAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether PIN auth is enabled
          example: false
        pin:
          type: string
          description: PIN value
          example: "1234"
      required:
        - enabled
        - pin
    BearerAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether bearer auth is enabled
          example: true
        distribution_groups:
          type: array
          items:
            type: string
            example: "ch8i4ug6lnn4g9hqv7mg"
          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
          example: false
      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
          example: "ds8i4ug6lnn4g9hqv7mg"
        domain:
          type: string
          description: Domain name
          example: "example.netbird.app"
        validated:
          type: boolean
          description: Whether the domain has been validated
          example: true
        type:
          $ref: '#/components/schemas/ReverseProxyDomainType'
        target_cluster:
          type: string
          description: The proxy cluster this domain is validated against (only for custom domains)
          example: "eu.proxy.netbird.io"
        supports_custom_ports:
          type: boolean
          description: Whether the cluster supports binding arbitrary TCP/UDP ports
          example: true
        require_subdomain:
          type: boolean
          description: Whether a subdomain label is required in front of this domain. When true, the domain cannot be used bare.
          example: false
      required:
        - id
        - domain
        - validated
        - type
    ReverseProxyDomainRequest:
      type: object
      properties:
        domain:
          type: string
          description: Domain name
          example: "myapp.example.com"
        target_cluster:
          type: string
          description: The proxy cluster this domain should be validated against
          example: "eu.proxy.netbird.io"
      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
    UsageStats:
      type: object
      properties:
        active_users:
          type: integer
          format: int64
          description: Number of active users.
          example: 15
        total_users:
          type: integer
          format: int64
          description: Total number of users.
          example: 20
        active_peers:
          type: integer
          format: int64
          description: Number of active peers.
          example: 10
        total_peers:
          type: integer
          format: int64
          description: Total number of peers.
          example: 25
      required:
        - active_users
        - total_users
        - active_peers
        - total_peers
    Product:
      type: object
      properties:
        name:
          type: string
          description: Name of the product.
          example: "Basic Plan"
        description:
          type: string
          description: Detailed description of the product.
          example: "This is the basic plan with limited features."
        features:
          type: array
          description: List of features provided by the product.
          items:
            type: string
          example: [ "5 free users", "Basic support" ]
        prices:
          type: array
          description: List of prices for the product in different currencies
          items:
            $ref: "#/components/schemas/Price"
        free:
          type: boolean
          description: Indicates whether the product is free or not.
          example: false
      required:
        - name
        - description
        - features
        - prices
        - free
    Price:
      type: object
      properties:
        price_id:
          type: string
          description: Unique identifier for the price.
          example: "price_H2KmRb4u1tP0sR7s"
        currency:
          type: string
          description: Currency code for this price.
          example: "USD"
        price:
          type: integer
          description: Price amount in minor units (e.g., cents).
          example: 1000
        unit:
          type: string
          description: Unit of measurement for this price (e.g., per user).
          example: "user"
      required:
        - price_id
        - currency
        - price
        - unit
    Subscription:
      type: object
      properties:
        active:
          type: boolean
          description: Indicates whether the subscription is active or not.
          example: true
        plan_tier:
          type: string
          description: The tier of the plan for the subscription.
          example: "basic"
        price_id:
          type: string
          description: Unique identifier for the price of the subscription.
          example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
        remaining_trial:
          type: integer
          description: The remaining time for the trial period, in seconds.
          example: 3600
        features:
          type: array
          description: List of features included in the subscription.
          items:
            type: string
          example: [ "free", "idp-sync", "audit-logs" ]
        currency:
          type: string
          description: Currency code of the subscription.
          example: "USD"
        price:
          type: integer
          description: Price amount in minor units (e.g., cents).
          example: 1000
        provider:
          type: string
          description: The provider of the subscription.
          example: [ "stripe", "aws" ]
        updated_at:
          type: string
          format: date-time
          description: The date and time when the subscription was last updated.
          example: "2021-08-01T12:00:00Z"
      required:
        - active
        - plan_tier
        - price_id
        - updated_at
        - currency
        - price
        - provider
    PortalResponse:
      type: object
      properties:
        session_id:
          type: string
          description: The unique identifier for the customer portal session.
          example: "cps_test_123456789"
        url:
          type: string
          description: URL to redirect the user to the customer portal.
          example: "https://billing.stripe.com/session/a1b2c3d4e5f6g7h8i9j0k"
      required:
        - session_id
        - url
    CheckoutResponse:
      type: object
      properties:
        session_id:
          type: string
          description: The unique identifier for the checkout session.
          example: "cs_test_a1b2c3d4e5f6g7h8i9j0"
        url:
          type: string
          description: URL to redirect the user to the checkout session.
          example: "https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6g7h8i9j0"
      required:
        - session_id
        - url
    StripeWebhookEvent:
      type: object
      properties:
        type:
          type: string
          description: The type of event received from Stripe.
          example: "customer.subscription.updated"
        data:
          type: object
          description: The data associated with the event from Stripe.
          example:
            object:
              id: "sub_123456789"
              object: "subscription"
              status: "active"
              items:
                object: "list"
                data:
                  - id: "si_123456789"
                    object: "subscription_item"
                    price:
                      id: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
                      object: "price"
                      unit_amount: 2000
                      currency: "usd"
              billing_cycle_anchor: 1609459200
    InvoiceResponse:
      type: object
      properties:
        id:
          type: string
          description: The Stripe invoice id
          example: "in_1MtHbELkdIwHu7ixl4OzzPMv"
        type:
          type: string
          description: The invoice type
          enum:
            - account
            - tenants
        period_start:
          type: string
          format: date-time
          description: The start date of the invoice period.
          example: "2021-08-01T12:00:00Z"
        period_end:
          type: string
          format: date-time
          description: The end date of the invoice period.
          example: "2021-08-31T12:00:00Z"
      required:
        - id
        - type
        - period_start
        - period_end
    InvoicePDFResponse:
      type: object
      properties:
        url:
          type: string
          description: URL to redirect the user to invoice.
          example: "https://invoice.stripe.com/i/acct_1M2DaBKina4I2KUb/test_YWNjdF8xTTJEdVBLaW5hM0kyS1ViLF1SeFpQdEJZd3lUOGNEajNqeWdrdXY2RFM4aHcyCnpsLDEzMjg3GTgyNQ02000JoIHc1X?s=db"
      required:
        - url
    MSPStatusResponse:
      type: object
      properties:
        id:
          type: string
          description: Tenant account ID (present only for tenants)
          example: ch8i4ug6lnn4g9hqv7m0
        parent:
          type: string
          description: Parent MSP account ID (present only for tenants)
          example: ch8i4ug6lnn4g9hqv7m1
        activated_at:
          type: string
          description: MSP or Tenant activation timestamp in RFC3339 format
          example: "2024-01-01T00:00:00Z"
        invited_at:
          type: string
          description: Tenant invitation timestamp in RFC3339 format (present only for tenants)
          example: "2024-01-01T00:00:00Z"
        status:
          type: string
          description: Tenant status (present only for tenants)
          enum: ["existing", "invited", "pending", "active"]
          example: active
        name:
          type: string
          description: MSP name (present only for MSP accounts)
          example: "My MSP"
        domain:
          type: string
          description: MSP domain (present only for MSP accounts)
          example: "msp.com"
        has_reseller:
          type: boolean
          description: Whether the MSP has a reseller (present only for MSP accounts)
          default: false
          example: false
        is_reseller:
          type: boolean
          description: Whether the account is a reseller
          default: false
          example: false
        parent_name:
          type: string
          description: Parent MSP name (present only for tenants)
          example: "My MSP"
        parent_domain:
          type: string
          description: Parent MSP domain (present only for tenants)
          example: "msp.com"
        parent_owner_name:
          type: string
          description: Parent MSP owner name
          example: "John Doe"
        parent_owner_email:
          type: string
          description: Parent MSP owner email
          example: "john@msp.com"
    ResellerStatusResponse:
      type: object
      properties:
        activated_at:
          type: string
          description: Reseller activation timestamp in RFC3339 format
          example: "2024-01-01T00:00:00Z"
        name:
          type: string
          description: Reseller name
          example: "My Reseller"
        domain:
          type: string
          description: Reseller domain
          example: "reseller.com"
        parent_owner_name:
          type: string
          description: Reseller owner name
          example: "John Doe"
        parent_owner_email:
          type: string
          description: Reseller owner email
          example: "john@reseller.com"
    ResellerMSPResponse:
      type: object
      properties:
        id:
          type: string
          description: The MSP account ID
          example: ch8i4ug6lnn4g9hqv7m0
        name:
          type: string
          description: The MSP name
          example: "Partner MSP"
        domain:
          type: string
          description: The MSP domain
          example: "partner-msp.com"
        has_reseller:
          type: boolean
          description: Whether the MSP is managed by a reseller
          example: true
        activated_at:
          type: string
          description: MSP activation timestamp in RFC3339 format
          example: "2024-01-01T00:00:00Z"
        invited_at:
          type: string
          description: MSP invitation timestamp in RFC3339 format
          example: "2024-01-01T00:00:00Z"
      required:
        - id
        - name
        - domain
        - has_reseller
    GetResellerMSPsResponse:
      type: array
      items:
        $ref: "#/components/schemas/ResellerMSPResponse"
    CreateResellerMSPRequest:
      type: object
      properties:
        name:
          type: string
          description: The name for the MSP
          example: "New Partner MSP"
        domain:
          type: string
          description: The domain for the MSP
          example: "new-partner.com"
      required:
        - name
        - domain
    CreateTenantRequest:
      type: object
      properties:
        name:
          type: string
          description: The name for the MSP tenant
          example: "My new tenant"
        domain:
          type: string
          description: The name for the MSP tenant
          example: "tenant.com"
        groups:
          description: MSP users Groups that can access the Tenant and Roles to assume
          type: array
          items:
            $ref: "#/components/schemas/TenantGroupResponse"
      required:
        - name
        - domain
        - groups
    UpdateTenantRequest:
      type: object
      properties:
        name:
          type: string
          description: The name for the MSP tenant
          example: "My new tenant"
        groups:
          description: MSP users Groups that can access the Tenant and Roles to assume
          type: array
          items:
            $ref: "#/components/schemas/TenantGroupResponse"
      required:
        - name
        - groups
    GetTenantsResponse:
      type: array
      items:
        $ref: "#/components/schemas/TenantResponse"
    DNSChallengeResponse:
      type: object
      properties:
        dns_challenge:
          type: string
          description: The DNS challenge to set in a TXT record
          example: YXNkYSBkYXNhc2Rhc2RhIGFzZGFzZDJhc2QyNDUxNQ
      required:
        - dns_challenge
    TenantGroupResponse:
      type: object
      properties:
        id:
          type: string
          description: The Group ID
          example: ch8i4ug6lnn4g9hqv7m0
        role:
          type: string
          description: The Role name
          example: "admin"
      required:
        - id
        - role
    TenantResponse:
      type: object
      properties:
        id:
          type: string
          description: The updated MSP tenant account ID
          example: ch8i4ug6lnn4g9hqv7m0
        name:
          type: string
          description: The name for the MSP tenant
          example: "My new tenant"
        domain:
          type: string
          description: The tenant account domain
          example: "tenant.com"
        groups:
          description: MSP users Groups that can access the Tenant and Roles to assume
          type: array
          items:
            $ref: "#/components/schemas/TenantGroupResponse"
        activated_at:
          type: string
          format: date-time
          description: The date and time when the tenant was activated.
          example: "2021-08-01T12:00:00Z"
        dns_challenge:
          type: string
          description: The DNS challenge to set in a TXT record
          example: YXNkYSBkYXNhc2Rhc2RhIGFzZGFzZDJhc2QyNDUxNQ
        created_at:
          type: string
          format: date-time
          description: The date and time when the tenant was created.
          example: "2021-08-01T12:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: The date and time when the tenant was last updated.
          example: "2021-08-01T12:00:00Z"
        invited_at:
          type: string
          format: date-time
          description: The date and time when the existing tenant was invited.
          example: "2021-08-01T12:00:00Z"
        status:
          type: string
          description: The status of the tenant
          enum:
            - existing
            - invited
            - pending
            - active
          example: "active"
      required:
        - id
        - name
        - domain
        - groups
        - created_at
        - updated_at
        - status
        - dns_challenge
    CreateIntegrationRequest:
      type: object
      description: "Request payload for creating a new event streaming integration. Also used as the structure for the PUT request body, but not all fields are applicable for updates (see PUT operation description)."
      required:
        - platform
        - config
        - enabled
      properties:
        platform:
          type: string
          description: The event streaming platform to integrate with (e.g., "datadog", "s3", "firehose"). This field is used for creation. For updates (PUT), this field, if sent, is ignored by the backend.
          enum: [ "datadog", "s3", "firehose", "generic_http" ]
          example: "s3"
        config:
          type: object
          additionalProperties:
            type: string
          description: Platform-specific configuration as key-value pairs. For creation, all necessary credentials and settings must be provided. For updates, provide the fields to change or the entire new configuration.
          example: { "bucket_name": "my-event-logs", "region": "us-east-1", "access_key_id": "AKIA...", "secret_access_key": "YOUR_SECRET_KEY" }
        enabled:
          type: boolean
          description: "Specifies whether the integration is enabled. During creation (POST), this value is sent by the client, but the provided backend manager function `CreateIntegration` does not appear to use it directly, so its effect on creation should be verified. During updates (PUT), this field is used to enable or disable the integration."
          example: true
    IntegrationResponse:
      type: object
      description: Represents an event streaming integration.
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
          minimum: 0
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "acc_abcdef123456"
        enabled:
          type: boolean
          description: Whether the integration is currently active.
          example: true
        platform:
          type: string
          description: The event streaming platform.
          enum: [ "datadog", "s3", "firehose", "generic_http" ]
          example: "datadog"
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        config:
          type: object
          additionalProperties:
            type: string
          description: Configuration for the integration. Sensitive keys (like API keys, secret keys) are masked with '****' in responses, as indicated by the GetIntegration handler logic.
          example: { "api_key": "****", "site": "datadoghq.com", "region": "us-east-1" }
    EDRIntuneRequest:
      type: object
      description: "Request payload for creating or updating a EDR Intune integration."
      required:
        - client_id
        - tenant_id
        - secret
        - groups
        - last_synced_interval
      properties:
        client_id:
          type: string
          description: The Azure application client id
        tenant_id:
          type: string
          description: The Azure tenant id
        secret:
          type: string
          description: The Azure application client secret
        groups:
          type: array
          description: The Groups this integrations applies to
          items:
            type: string
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours. Minimum value is 24 hours.
          minimum: 24
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
    EDRIntuneResponse:
      type: object
      description: Represents a Intune EDR integration configuration
      required:
        - id
        - account_id
        - created_by
        - last_synced_at
        - created_at
        - updated_at
        - client_id
        - tenant_id
        - groups
        - last_synced_interval
        - enabled
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
          minimum: 0
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "acc_abcdef123456"
        last_synced_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last synced.
          example: "2023-05-15T10:30:00Z"
        created_by:
          type: string
          description: The user id that created the integration
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        client_id:
          type: string
          description: The Azure application client id
          example: "acc_abcdef123456"
        tenant_id:
          type: string
          description: The Azure tenant id
          example: "acc_abcdef123456"
        groups:
          type: array
          description: List of groups
          items:
            $ref: '#/components/schemas/Group'
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours.
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
    EDRSentinelOneRequest:
      type: object
      description: Request payload for creating or updating a EDR SentinelOne integration
      properties:
        api_token:
          type: string
          description: SentinelOne API token
        api_url:
          type: string
          description: The Base URL of SentinelOne API
        groups:
          type: array
          description: The Groups this integrations applies to
          items:
            type: string
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours. Minimum value is 24 hours.
          minimum: 24
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
        match_attributes:
          $ref: '#/components/schemas/SentinelOneMatchAttributes'
      required:
        - api_token
        - api_url
        - groups
        - last_synced_interval
        - match_attributes
    EDRSentinelOneResponse:
      type: object
      description: Represents a SentinelOne EDR integration configuration
      required:
        - id
        - account_id
        - created_by
        - last_synced_at
        - created_at
        - updated_at
        - api_url
        - groups
        - last_synced_interval
        - match_attributes
        - enabled
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "ch8i4ug6lnn4g9hqv7l0"
        last_synced_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last synced.
          example: "2023-05-15T10:30:00Z"
        created_by:
          type: string
          description: The user id that created the integration
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        api_url:
          type: string
          description: The Base URL of SentinelOne API
        groups:
          type: array
          description: List of groups
          items:
            $ref: '#/components/schemas/Group'
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours.
        match_attributes:
          $ref: '#/components/schemas/SentinelOneMatchAttributes'
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
    SentinelOneMatchAttributes:
      type: object
      description: Attribute conditions to match when approving agents
      additionalProperties: false
      properties:
        active_threats:
          description: The maximum allowed number of active threats on the agent
          type: integer
          example: 0
        encrypted_applications:
          description: Whether disk encryption is enabled on the agent
          type: boolean
        firewall_enabled:
          description: Whether the agent firewall is enabled
          type: boolean
        infected:
          description: Whether the agent is currently flagged as infected
          type: boolean
        is_active:
          description: Whether the agent has been recently active and reporting
          type: boolean
        is_up_to_date:
          description: Whether the agent is running the latest available version
          type: boolean
        network_status:
          description: The current network connectivity status of the device
          type: string
          enum: [ "connected", "disconnected", "quarantined" ]
        operational_state:
          description: The current operational state of the agent
          type: string

    EDRFalconRequest:
      type: object
      description: Request payload for creating or updating a EDR Falcon integration
      properties:
        client_id:
          type: string
          description: CrowdStrike API client ID
        secret:
          type: string
          description: CrowdStrike API client secret
        cloud_id:
          type: string
          description: CrowdStrike cloud identifier (e.g., "us-1", "us-2", "eu-1")
        groups:
          type: array
          description: The Groups this integration applies to
          items:
            type: string
        zta_score_threshold:
          type: integer
          description: The minimum Zero Trust Assessment score required for agent approval (0-100)
          minimum: 0
          maximum: 100
          example: 75
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
      required:
        - client_id
        - secret
        - cloud_id
        - groups
        - zta_score_threshold
    EDRFalconResponse:
      type: object
      description: Represents a Falcon EDR integration
      required:
        - id
        - account_id
        - last_synced_at
        - created_by
        - created_at
        - updated_at
        - cloud_id
        - groups
        - zta_score_threshold
        - enabled
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "ch8i4ug6lnn4g9hqv7l0"
        last_synced_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last synced.
          example: "2023-05-15T10:30:00Z"
        created_by:
          type: string
          description: The user id that created the integration
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        cloud_id:
          type: string
          description: CrowdStrike cloud identifier
        groups:
          type: array
          description: List of groups
          items:
            $ref: '#/components/schemas/Group'
        zta_score_threshold:
          type: integer
          description: The minimum Zero Trust Assessment score required for agent approval (0-100)
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled

    EDRHuntressRequest:
      type: object
      description: Request payload for creating or updating a EDR Huntress integration
      properties:
        api_key:
          type: string
          description: Huntress API key
        api_secret:
          type: string
          description: Huntress API secret
        groups:
          type: array
          description: The Groups this integrations applies to
          items:
            type: string
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours. Minimum value is 24 hours
          minimum: 24
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
        match_attributes:
          $ref: '#/components/schemas/HuntressMatchAttributes'
      required:
        - api_key
        - api_secret
        - groups
        - last_synced_interval
        - match_attributes
    EDRHuntressResponse:
      type: object
      description: Represents a Huntress EDR integration configuration
      required:
        - id
        - account_id
        - created_by
        - last_synced_at
        - created_at
        - updated_at
        - groups
        - last_synced_interval
        - match_attributes
        - enabled
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "ch8i4ug6lnn4g9hqv7l0"
        last_synced_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last synced.
          example: "2023-05-15T10:30:00Z"
        created_by:
          type: string
          description: The user id that created the integration
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        groups:
          type: array
          description: List of groups
          items:
            $ref: '#/components/schemas/Group'
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours.
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
        match_attributes:
          $ref: '#/components/schemas/HuntressMatchAttributes'

    HuntressMatchAttributes:
      type: object
      description: Attribute conditions to match when approving agents
      additionalProperties: false
      properties:
        defender_policy_status:
          type: string
          description: Policy status of Defender AV for Managed Antivirus.
          example: "Compliant"
        defender_status:
          type: string
          description: Status of Defender AV Managed Antivirus.
          example: "Healthy"
        defender_substatus:
          type: string
          description: Sub-status of Defender AV Managed Antivirus.
          example: "Up to date"
        firewall_status:
          type: string
          description: Status of agent firewall. Can be one of Disabled, Enabled, Pending Isolation, Isolated, Pending Release.
          example: "Enabled"

    CreateScimIntegrationRequest:
      type: object
      description: Request payload for creating an SCIM IDP integration
      required:
        - prefix
        - provider
      properties:
        prefix:
          type: string
          description: The connection prefix used for the SCIM provider
        provider:
          type: string
          description: Name of the SCIM identity provider
        group_prefixes:
          type: array
          description: List of start_with string patterns for groups to sync
          items:
            type: string
          example: [ "Engineering", "Sales" ]
        user_group_prefixes:
          type: array
          description: List of start_with string patterns for groups which users to sync
          items:
            type: string
          example: [ "Users" ]
    UpdateScimIntegrationRequest:
      type: object
      description: Request payload for updating an SCIM IDP integration
      properties:
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          example: true
        group_prefixes:
          type: array
          description: List of start_with string patterns for groups to sync
          items:
            type: string
          example: [ "Engineering", "Sales" ]
        user_group_prefixes:
          type: array
          description: List of start_with string patterns for groups which users to sync
          items:
            type: string
          example: [ "Users" ]
    ScimIntegration:
      type: object
      description: Represents a SCIM IDP integration
      required:
        - id
        - enabled
        - provider
        - group_prefixes
        - user_group_prefixes
        - auth_token
        - last_synced_at
      properties:
        id:
          type: integer
          format: int64
          description: The unique identifier for the integration
          example: 123
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          example: true
        provider:
          type: string
          description: Name of the SCIM identity provider
        group_prefixes:
          type: array
          description: List of start_with string patterns for groups to sync
          items:
            type: string
          example: [ "Engineering", "Sales" ]
        user_group_prefixes:
          type: array
          description: List of start_with string patterns for groups which users to sync
          items:
            type: string
          example: [ "Users" ]
        auth_token:
          type: string
          description: SCIM API token (full on creation, masked otherwise)
          example: "nbs_abc***********************************"
        last_synced_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last synced
          example: "2023-05-15T10:30:00Z"
    IdpIntegrationSyncLog:
      type: object
      description: Represents a synchronization log entry for an integration
      required:
        - id
        - level
        - timestamp
        - message
      properties:
        id:
          type: integer
          format: int64
          description: The unique identifier for the sync log
          example: 123
        level:
          type: string
          description: The log level
          example: "info"
        timestamp:
          type: string
          format: date-time
          description: Timestamp of when the log was created
          example: "2023-05-15T10:30:00Z"
        message:
          type: string
          description: Log message
          example: "Successfully synchronized users and groups"
    ScimTokenResponse:
      type: object
      description: Response containing the regenerated SCIM token
      required:
        - auth_token
      properties:
        auth_token:
          type: string
          description: The newly generated SCIM API token
          example: "nbs_F3f0d..."
    NotificationChannelType:
      type: string
      description: The type of notification channel.
      enum:
        - email
        - webhook
      example: "email"
    NotificationEventType:
      type: string
      description: |
        An activity event type code. See `GET /api/integrations/notifications/types` for the full list
        of supported event types and their human-readable descriptions.
      example: "user.join"
    EmailTarget:
      type: object
      description: Target configuration for email notification channels.
      properties:
        emails:
          type: array
          description: List of email addresses to send notifications to.
          minItems: 1
          items:
            type: string
            format: email
          example: [ "admin@example.com", "ops@example.com" ]
      required:
        - emails
    WebhookTarget:
      type: object
      description: Target configuration for webhook notification channels.
      properties:
        url:
          type: string
          format: uri
          description: The webhook endpoint URL to send notifications to.
          example: "https://hooks.example.com/netbird"
        headers:
          type: object
          additionalProperties:
            type: string
          description: |
            Custom HTTP headers sent with each webhook request.
            Values are write-only; in GET responses all values are masked.
          example:
            Authorization: "Bearer token"
            X-Webhook-Secret: "secret"
      required:
        - url
    NotificationChannelRequest:
      type: object
      description: Request body for creating or updating a notification channel.
      properties:
        type:
          $ref: '#/components/schemas/NotificationChannelType'
        target:
          description: |
            Channel-specific target configuration. The shape depends on the `type` field:
            - `email`: requires an `EmailTarget` object
            - `webhook`: requires a `WebhookTarget` object
          oneOf:
            - $ref: '#/components/schemas/EmailTarget'
            - $ref: '#/components/schemas/WebhookTarget'
        event_types:
          type: array
          description: List of activity event type codes this channel subscribes to.
          items:
            $ref: '#/components/schemas/NotificationEventType'
          example: [ "user.join", "peer.user.add", "peer.login.expire" ]
        enabled:
          type: boolean
          description: Whether this notification channel is active.
          example: true
      required:
        - type
        - event_types
        - enabled
    NotificationChannelResponse:
      type: object
      description: A notification channel configuration.
      properties:
        id:
          type: string
          description: Unique identifier of the notification channel.
          readOnly: true
          example: "ch8i4ug6lnn4g9hqv7m0"
        type:
          $ref: '#/components/schemas/NotificationChannelType'
        target:
          description: |
            Channel-specific target configuration. The shape depends on the `type` field:
            - `email`: an `EmailTarget` object
            - `webhook`: a `WebhookTarget` object
          oneOf:
            - $ref: '#/components/schemas/EmailTarget'
            - $ref: '#/components/schemas/WebhookTarget'
        event_types:
          type: array
          description: List of activity event type codes this channel subscribes to.
          items:
            $ref: '#/components/schemas/NotificationEventType'
          example: [ "user.join", "peer.user.add", "peer.login.expire" ]
        enabled:
          type: boolean
          description: Whether this notification channel is active.
          example: true
      required:
        - id
        - type
        - event_types
        - enabled
    NotificationTypeEntry:
      type: object
      description: A map of event type codes to their human-readable descriptions.
      additionalProperties:
        type: string
      example:
        user.join: "User joined"
    BypassResponse:
      type: object
      description: Response for bypassed peer operations.
      required:
        - peer_id
      properties:
        peer_id:
          type: string
          description: The ID of the bypassed peer.
          example: "chacbco6lnnbn6cg5s91"
    ErrorResponse:
      type: object
      description: "Standard error response. Note: The exact structure of this error response is inferred from `util.WriteErrorResponse` and `util.WriteError` usage in the provided Go code, as a specific Go struct for errors was not provided."
      properties:
        message:
          type: string
          description: A human-readable error message.
          example: "couldn't parse JSON request"
  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: { }
    conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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: sort_by
          schema:
            type: string
            enum: [timestamp, url, host, path, method, status_code, duration, source_ip, user_id, auth_method, reason]
            default: timestamp
          description: Field to sort by (url sorts by host then path)
        - in: query
          name: sort_order
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort order (ascending or descending)
        - in: query
          name: search
          schema:
            type: string
          description: General search across request ID, 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/integrations/billing/usage:
    get:
      summary: Get current usage
      tags:
        - Usage
      responses:
        "200":
          description: Current usage data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageStats"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/subscription:
    get:
      summary: Get current subscription
      tags:
        - Subscription
      responses:
        "200":
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: No subscription found
        "500":
          $ref: "#/components/responses/internal_error"
    put:
      summary: Change subscription
      tags:
        - Subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                priceID:
                  type: string
                  description: The Price ID to change the subscription to.
                  example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
                plan_tier:
                  type: string
                  description: The plan tier to change the subscription to.
                  example: business
      responses:
        "200":
          description: Subscription successfully changed
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/plans:
    get:
      summary: Get available plans
      tags:
        - Plans
      responses:
        "200":
          description: List of available plans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Product"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/checkout:
    post:
      summary: Create checkout session
      tags:
        - Checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                baseURL:
                  type: string
                  description: The base URL for the redirect after checkout.
                  example: "https://app.netbird.io/plans/success"
                priceID:
                  type: string
                  description: The Price ID for checkout.
                  example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
                enableTrial:
                  type: boolean
                  description: Enables a 14-day trial for the account.
              required:
                - baseURL
                - priceID
      responses:
        "200":
          description: Checkout session URL
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckoutResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/portal:
    get:
      summary: Get customer portal URL
      tags:
        - Portal
      parameters:
        - in: query
          name: baseURL
          schema:
            type: string
          required: true
          description: The base URL for the redirect after accessing the portal.
          example: "https://app.netbird.io/plans"
      responses:
        "200":
          description: Customer portal URL
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortalResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/invoices:
    get:
      summary: Get account's paid invoices
      tags:
        - Invoice
      responses:
        "200":
          description: The account's paid invoices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/InvoiceResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/invoices/{id}/pdf:
    get:
      summary: Get account invoice URL to Stripe.
      tags:
        - Invoice
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the invoice
      responses:
        "200":
          description: The invoice URL to Stripe
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvoicePDFResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/invoices/{id}/csv:
    get:
      summary: Get account invoice CSV.
      tags:
        - Invoice
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the invoice
      responses:
        "200":
          description: The invoice CSV
          headers:
            Content-Disposition:
              schema:
                type: string
              example: attachment; filename=in_1MtHbELkdIwHu7ixl4OzzPMv.csv
          content:
            text/csv:
              schema:
                type: string
              example: |
                description,qty,unit_price,amount
                line item 2, 5, 1.00, 5.00
                line item 1, 10, 0.50, 5.00
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/aws/marketplace/activate:
    post:
      summary: Activate AWS Marketplace subscription.
      tags:
        - AWS Marketplace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan_tier:
                  type: string
                  description: The plan tier to activate the subscription for.
                  example: business
              required:
                - plan_tier
      responses:
        "200":
          description: AWS subscription successfully activated
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/aws/marketplace/enrich:
    post:
      summary: Enrich AWS Marketplace subscription with Account ID.
      tags:
        - AWS Marketplace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                aws_user_id:
                  type: string
                  description: The AWS user ID.
                  example: eRF345hgdgFyu
              required:
                - aws_user_id
      responses:
        "200":
          description: AWS subscription successfully enriched with Account ID.
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp:
    get:
      summary: Get MSP or Tenant status
      description: Returns the MSP, Tenant, or Reseller status of the authenticated account
      tags:
        - MSP
      responses:
        "200":
          description: MSP or Tenant status response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MSPStatusResponse"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
    post:
      summary: Create MSP account
      description: Activates the authenticated account as an MSP
      tags:
        - MSP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invite:
                  type: string
                  description: The invite code
                  example: "705860a1-27a3-4976-bf63-c5cd2fc1582b"
              required:
                - invite
      responses:
        "200":
          description: MSP account created or already exists
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "403":
          $ref: "#/components/responses/forbidden"
        "412":
          description: MSP account requirements not met
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/reseller:
    get:
      summary: Get Reseller status
      description: Returns the reseller status of the authenticated account
      tags:
        - MSP
      responses:
        "200":
          description: Reseller status response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResellerStatusResponse"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
    post:
      summary: Activate Reseller account
      description: Activates the authenticated account as a reseller
      tags:
        - MSP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invite:
                  type: string
                  description: The invite code
                  example: "705860a1-27a3-4976-bf63-c5cd2fc1582b"
              required:
                - invite
      responses:
        "200":
          description: Reseller account activated or already exists
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "403":
          $ref: "#/components/responses/forbidden"
        "412":
          description: Reseller account requirements not met
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/reseller/msps:
    get:
      summary: List MSPs under reseller
      tags:
        - MSP
      responses:
        "200":
          description: List of MSPs managed by the reseller
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetResellerMSPsResponse"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "403":
          $ref: "#/components/responses/forbidden"
        "500":
          $ref: "#/components/responses/internal_error"
    post:
      summary: Create MSP under reseller
      description: Creates a new MSP account managed by the reseller. No domain validation required.
      tags:
        - MSP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateResellerMSPRequest"
      responses:
        "200":
          description: MSP created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResellerMSPResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "403":
          $ref: "#/components/responses/forbidden"
        "409":
          description: MSP already exists for this domain
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/reseller/msps/{id}:
    delete:
      summary: Unlink MSP from reseller
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The MSP account ID to unlink
      responses:
        "200":
          description: MSP unlinked successfully
        "401":
          $ref: "#/components/responses/requires_authentication"
        "403":
          $ref: "#/components/responses/forbidden"
        "404":
          description: MSP not found or not managed by this reseller
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/reseller/msps/{id}/invite:
    post:
      summary: Invite existing MSP to reseller
      description: Sends an invitation to an existing MSP to join the reseller
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The MSP account ID to invite
      responses:
        "200":
          description: Invitation sent successfully
        "401":
          $ref: "#/components/responses/requires_authentication"
        "403":
          $ref: "#/components/responses/forbidden"
        "404":
          description: MSP not found
        "412":
          description: MSP is already managed by a reseller
        "500":
          $ref: "#/components/responses/internal_error"
    put:
      summary: Accept or decline reseller invitation
      description: MSP owner accepts or declines an invitation from a reseller
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The MSP account ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: string
                  description: Accept or decline the invitation
                  enum:
                    - accept
                    - decline
              required:
                - value
      responses:
        "200":
          description: Invitation response processed
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "403":
          $ref: "#/components/responses/forbidden"
        "404":
          description: MSP not found or no pending invitation
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/tenants:
    get:
      summary: Get MSP tenants
      tags:
        - MSP
      responses:
        "200":
          description: Get MSP tenants response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetTenantsResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
    post:
      summary: Create MSP tenant
      tags:
        - MSP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTenantRequest"
      responses:
        "200":
          description: Create MSP tenant Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/tenants/{id}:
    put:
      summary: Update MSP tenant
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of a tenant account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTenantRequest"
      responses:
        "200":
          description: Update MSP tenant Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/tenants/{id}/unlink:
    post:
      summary: Unlink a tenant
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of a tenant account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                owner:
                  type: string
                  description: The new owners user ID.
                  example: "google-oauth2|123456789012345678901"
              required:
                - owner
      responses:
        "200":
          description: Successfully unlinked the tenant
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: The tenant was not found
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/tenants/{id}/dns:
    post:
      summary: Verify a tenant domain DNS challenge
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of a tenant account
      responses:
        "200":
          description: Successfully verified the DNS challenge
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: The tenant was not found
        "500":
          $ref: "#/components/responses/internal_error"
        "501":
          description: DNS Challenge Failed Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DNSChallengeResponse"
  /api/integrations/msp/tenants/{id}/subscription:
    post:
      summary: Create subscription for Tenant
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of a tenant account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                priceID:
                  type: string
                  description: The Price ID to change the subscription to.
                  example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
              required:
                - priceID
      responses:
        "200":
          description: Successfully created subscription for Tenant
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: The tenant was not found
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/tenants/{id}/invite:
    post:
      summary: Invite existing account as a Tenant to the MSP account
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of an existing tenant account
      responses:
        "200":
          description: Successfully invited existing Tenant to the MSP account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: The tenant was not found
        "500":
          $ref: "#/components/responses/internal_error"
    put:
      summary: Response by the invited Tenant account owner
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of an existing tenant account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: string
                  description: Accept or decline the invitation.
                  enum:
                    - accept
                    - decline
              required:
                - value
      responses:
        "200":
          description: Successful response
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: The tenant was not found
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/edr/intune:
    post:
      tags:
        - EDR Intune Integrations
      summary: Create EDR Intune Integration
      description: |
        Creates a new EDR Intune integration for the authenticated account.
      operationId: createEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRIntuneRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRIntuneResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - EDR Intune Integrations
      summary: Get EDR Intune Integration
      description: Retrieves a specific EDR Intune integration by its ID.
      operationId: getEDRIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details. Config keys are masked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRIntuneResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - EDR Intune Integrations
      summary: Update EDR Intune Integration
      description: |
        Updates an existing EDR Intune Integration. The request body structure is `EDRIntuneRequest`.
      operationId: updateEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRIntuneRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRIntuneResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR Intune Integrations
      summary: Delete EDR Intune Integration
      description: Deletes an EDR Intune Integration by its ID.
      operationId: deleteIntegration
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/edr/sentinelone:
    post:
      tags:
        - EDR SentinelOne Integrations
      summary: Create EDR SentinelOne Integration
      description: Creates a new EDR SentinelOne integration
      operationId: createSentinelOneEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRSentinelOneRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRSentinelOneResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - EDR SentinelOne Integrations
      summary: Get EDR SentinelOne Integration
      description: Retrieves a specific EDR SentinelOne integration by its ID.
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRSentinelOneResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - EDR SentinelOne Integrations
      summary: Update EDR SentinelOne Integration
      description: Updates an existing EDR SentinelOne Integration.
      operationId: updateSentinelOneEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRSentinelOneRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRSentinelOneResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR SentinelOne Integrations
      summary: Delete EDR SentinelOne Integration
      description: Deletes an EDR SentinelOne Integration by its ID.
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/integrations/edr/falcon:
    post:
      tags:
        - EDR Falcon Integrations
      summary: Create EDR Falcon Integration
      description: Creates a new EDR Falcon integration
      operationId: createFalconEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRFalconRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRFalconResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - EDR Falcon Integrations
      summary: Get EDR Falcon Integration
      description: Retrieves a specific EDR Falcon integration by its ID.
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRFalconResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - EDR Falcon Integrations
      summary: Update EDR Falcon Integration
      description: Updates an existing EDR Falcon Integration.
      operationId: updateFalconEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRFalconRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRFalconResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR Falcon Integrations
      summary: Delete EDR Falcon Integration
      description: Deletes an existing EDR Falcon Integration by its ID.
      responses:
        '202':
          description: Integration deleted successfully. Typically returns no content.
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/integrations/scim-idp:
    post:
      tags:
        - IDP
      summary: Create SCIM IDP Integration
      description: Creates a new SCIM integration
      operationId: createSCIMIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScimIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - IDP
      summary: Get All SCIM IDP Integrations
      description: Retrieves all SCIM IDP integrations for the authenticated account
      operationId: getAllSCIMIntegrations
      responses:
        '200':
          description: A list of SCIM IDP integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScimIntegration'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/scim-idp/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the SCIM IDP integration.
        schema:
          type: string
          example: "ch8i4ug6lnn4g9hqv7m0"
    get:
      tags:
        - IDP
      summary: Get SCIM IDP Integration
      description: Retrieves an SCIM IDP integration by ID.
      operationId: getSCIMIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimIntegration'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - IDP
      summary: Update SCIM IDP Integration
      description: Updates an existing SCIM IDP Integration.
      operationId: updateSCIMIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScimIntegrationRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - IDP
      summary: Delete SCIM IDP Integration
      description: Deletes an SCIM IDP integration by ID.
      operationId: deleteSCIMIntegration
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/scim-idp/{id}/token:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the SCIM IDP integration.
        schema:
          type: string
          example: "ch8i4ug6lnn4g9hqv7m0"
    post:
      tags:
        - IDP
      summary: Regenerate SCIM Token
      description: Regenerates the SCIM API token for an SCIM IDP integration.
      operationId: regenerateSCIMToken
      responses:
        '200':
          description: Token regenerated successfully. Returns the new token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimTokenResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/scim-idp/{id}/logs:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the SCIM IDP integration.
        schema:
          type: string
          example: "ch8i4ug6lnn4g9hqv7m0"
    get:
      tags:
        - IDP
      summary: Get SCIM Integration Sync Logs
      description: Retrieves synchronization logs for a SCIM IDP integration.
      operationId: getSCIMIntegrationLogs
      responses:
        '200':
          description: Successfully retrieved the integration sync logs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdpIntegrationSyncLog'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/integrations/edr/huntress:
    post:
      tags:
        - EDR Huntress Integrations
      summary: Create EDR Huntress Integration
      description: Creates a new EDR Huntress integration
      operationId: createHuntressEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRHuntressRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRHuntressResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - EDR Huntress Integrations
      summary: Get EDR Huntress Integration
      description: Retrieves a specific EDR Huntress integration by its ID.
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRHuntressResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - EDR Huntress Integrations
      summary: Update EDR Huntress Integration
      description: Updates an existing EDR Huntress Integration.
      operationId: updateHuntressEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRHuntressRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRHuntressResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR Huntress Integrations
      summary: Delete EDR Huntress Integration
      description: Deletes an EDR Huntress Integration by its ID.
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/peers/{peer-id}/edr/bypass:
    parameters:
      - name: peer-id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the peer
    post:
      tags:
        - EDR Peers
      summary: Bypass compliance for a non-compliant peer
      description: |
        Allows an admin to bypass EDR compliance checks for a specific peer.
        The peer will remain bypassed until the admin revokes it OR the device becomes
        naturally compliant in the EDR system.
      operationId: bypassCompliance
      responses:
        '200':
          description: Peer compliance bypassed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BypassResponse'
        '400':
          description: Bad Request (peer not in non-compliant state)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR Peers
      summary: Revoke compliance bypass for a peer
      description: Removes the compliance bypass, subjecting the peer to normal EDR validation.
      operationId: revokeBypass
      responses:
        '200':
          description: Compliance bypass revoked successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/peers/edr/bypassed:
    get:
      tags:
        - EDR Peers
      summary: List all bypassed peers
      description: Returns all peers that have compliance bypassed by an admin.
      operationId: listBypassedPeers
      responses:
        '200':
          description: List of bypassed peers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BypassResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/event-streaming:
    post:
      tags:
        - Event Streaming Integrations
      summary: Create Event Streaming Integration
      description: |
        Creates a new event streaming integration for the authenticated account.
        The request body should conform to `CreateIntegrationRequest`.
        Note: Based on the provided Go code, the `enabled` field from the request is part of the `CreateIntegrationRequest` struct,
        but the backend `manager.CreateIntegration` function signature shown does not directly use this `enabled` field.
        The actual behavior for `enabled` during creation should be confirmed (e.g., it might have a server-side default or be handled by other logic).
      operationId: createIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - Event Streaming Integrations
      summary: List Event Streaming Integrations
      description: Retrieves all event streaming integrations for the authenticated account.
      operationId: getAllIntegrations
      responses:
        '200':
          description: A list of event streaming integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IntegrationResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/event-streaming/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique numeric identifier of the event streaming integration.
        schema:
          type: integer
          example: 123
    get:
      tags:
        - Event Streaming Integrations
      summary: Get Event Streaming Integration
      description: Retrieves a specific event streaming integration by its ID.
      operationId: getIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details. Config keys are masked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Event Streaming Integrations
      summary: Update Event Streaming Integration
      description: |
        Updates an existing event streaming integration. The request body structure is `CreateIntegrationRequest`.
        However, for updates:
        - The `platform` field, if provided in the body, is ignored by the backend manager function, as the platform of an existing integration is typically immutable.
        - The `enabled` and `config` fields from the request body are used to update the integration.
      operationId: updateIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIntegrationRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Event Streaming Integrations
      summary: Delete Event Streaming Integration
      description: Deletes an event streaming integration by its ID.
      operationId: deleteIntegration
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/reverse-proxies/clusters:
    get:
      summary: List available proxy clusters
      description: Returns a list of available proxy clusters with their connection status
      tags: [ Services ]
      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/services:
    get:
      summary: List all Services
      description: Returns a list of all reverse proxy services
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of services
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Service
      description: Creates a new reverse proxy service
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New service request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequest'
      responses:
        '200':
          description: Service created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '409':
          "$ref": "#/components/responses/conflict"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/services/{serviceId}:
    get:
      summary: Retrieve a Service
      description: Get information about a specific reverse proxy service
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: serviceId
          required: true
          schema:
            type: string
          description: The unique identifier of a service
      responses:
        '200':
          description: A service object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '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 Service
      description: Update an existing service
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: serviceId
          required: true
          schema:
            type: string
          description: The unique identifier of a service
      requestBody:
        description: Service update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequest'
      responses:
        '200':
          description: Service updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '409':
          "$ref": "#/components/responses/conflict"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Service
      description: Delete an existing service
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: serviceId
          required: true
          schema:
            type: string
          description: The unique identifier of a service
      responses:
        '200':
          description: Service 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 Service Domains
      description: Get information about domains that can be used for service endpoints.
      tags: [ Services ]
      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 service endpoints, this will trigger an initial validation check
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: Custom domain creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReverseProxyDomainRequest'
      responses:
        '200':
          description: Service created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '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 service custom domain
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: domainId
          required: true
          schema:
            type: string
          description: The custom domain ID
      responses:
        '204':
          description: Service 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: [ Services ]
      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"
  /api/integrations/notifications/types:
    get:
      tags:
        - Notifications
      summary: List Notification Event Types
      description: |
        Returns a map of all supported activity event type codes to their
        human-readable descriptions. Use these codes when configuring
        `event_types` on notification channels.
      operationId: listNotificationEventTypes
      responses:
        '200':
          description: A map of event type codes to descriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTypeEntry'
        '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/integrations/notifications/channels:
    get:
      tags:
        - Notifications
      summary: List Notification Channels
      description: Retrieves all notification channels configured for the authenticated account.
      operationId: listNotificationChannels
      responses:
        '200':
          description: A list of notification channels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationChannelResponse'
        '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:
      tags:
        - Notifications
      summary: Create Notification Channel
      description: |
        Creates a new notification channel for the authenticated account.
        Supported channel types are `email` and `webhook`.
      operationId: createNotificationChannel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationChannelRequest'
      responses:
        '200':
          description: Notification channel created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '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/integrations/notifications/channels/{channelId}:
    parameters:
      - name: channelId
        in: path
        required: true
        description: The unique identifier of the notification channel.
        schema:
          type: string
          example: "ch8i4ug6lnn4g9hqv7m0"
    get:
      tags:
        - Notifications
      summary: Get Notification Channel
      description: Retrieves a specific notification channel by its ID.
      operationId: getNotificationChannel
      responses:
        '200':
          description: Successfully retrieved the notification channel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '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:
      tags:
        - Notifications
      summary: Update Notification Channel
      description: Updates an existing notification channel.
      operationId: updateNotificationChannel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationChannelRequest'
      responses:
        '200':
          description: Notification channel updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '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:
      tags:
        - Notifications
      summary: Delete Notification Channel
      description: Deletes a notification channel by its ID.
      operationId: deleteNotificationChannel
      responses:
        '200':
          description: Notification channel deleted successfully.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '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"