Services - NetBird API

GET/api/reverse-proxies/services

List all Services

Returns a list of all reverse proxy services

Request

GET

/api/reverse-proxies/services

curl -X GET https://api.netbird.io/api/reverse-proxies/services \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

[
  {
    "id": {
      "type": "string",
      "description": "Service ID"
    },
    "name": {
      "type": "string",
      "description": "Service name"
    },
    "domain": {
      "type": "string",
      "description": "Domain for the service"
    },
    "proxy_cluster": "eu.proxy.netbird.io",
    "targets": [
      {
        "target_id": {
          "type": "string",
          "description": "Target ID"
        },
        "target_type": {
          "type": "string",
          "description": "Target type (e.g., \"peer\", \"resource\")",
          "enum": [
            "peer",
            "resource"
          ]
        },
        "path": {
          "type": "string",
          "description": "URL path prefix for this target"
        },
        "protocol": {
          "type": "string",
          "description": "Protocol to use when connecting to the backend",
          "enum": [
            "http",
            "https"
          ]
        },
        "host": {
          "type": "string",
          "description": "Backend ip or domain for this target"
        },
        "port": {
          "type": "integer",
          "description": "Backend port for this target. Use 0 or omit to use the scheme default (80 for http, 443 for https)."
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether this target is enabled"
        },
        "options": {
          "skip_tls_verify": {
            "type": "boolean",
            "description": "Skip TLS certificate verification for this backend"
          },
          "request_timeout": {
            "type": "string",
            "description": "Per-target response timeout as a Go duration string (e.g. \"30s\", \"2m\")"
          },
          "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"
            ]
          },
          "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]*$"
            }
          }
        }
      }
    ],
    "enabled": {
      "type": "boolean",
      "description": "Whether the service is enabled"
    },
    "pass_host_header": {
      "type": "boolean",
      "description": "When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address"
    },
    "rewrite_redirects": {
      "type": "boolean",
      "description": "When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain"
    },
    "auth": {
      "password_auth": {
        "enabled": {
          "type": "boolean",
          "description": "Whether password auth is enabled"
        },
        "password": {
          "type": "string",
          "description": "Auth password"
        }
      },
      "pin_auth": {
        "enabled": {
          "type": "boolean",
          "description": "Whether PIN auth is enabled"
        },
        "pin": {
          "type": "string",
          "description": "PIN value"
        }
      },
      "bearer_auth": {
        "enabled": {
          "type": "boolean",
          "description": "Whether bearer auth is enabled"
        },
        "distribution_groups": [
          {
            "type": "string"
          }
        ]
      },
      "link_auth": {
        "enabled": {
          "type": "boolean",
          "description": "Whether link auth is enabled"
        }
      }
    },
    "meta": {
      "created_at": "2024-02-03T10:30:00Z",
      "certificate_issued_at": "2024-02-03T10:35:00Z",
      "status": "active"
    }
  }
]

POST/api/reverse-proxies/services

Create a Service

Creates a new reverse proxy service

Request-Body Parameters

Name
name
Type
string
Required
required
Enum
Description
Service name
Name
domain
Type
string
Required
required
Enum
Description
Domain for the service
Name
targets
Type
object[]
Required
required
Enum
Description
List of target backends for this service
Name
target_id
Type
string
Required
required
Enum
Description
Target ID
Name
target_type
Type
string
Required
required
Enum
Description
Target type (e.g., "peer", "resource")
Name
path
Type
string
Required
optional
Enum
Description
URL path prefix for this target
Name
protocol
Type
string
Required
required
Enum
Description
Protocol to use when connecting to the backend
Name
host
Type
string
Required
optional
Enum
Description
Backend ip or domain for this target
Name
port
Type
integer
Required
required
Enum
Description
Backend port for this target. Use 0 or omit to use the scheme default (80 for http, 443 for https).
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether this target is enabled
Name
options
Type
object
Required
optional
Enum
Description
More Information
Name
skip_tls_verify
Type
boolean
Required
optional
Enum
Description
Skip TLS certificate verification for this backend
Name
request_timeout
Type
string
Required
optional
Enum
Description
Per-target response timeout as a Go duration string (e.g. "30s", "2m")
Name
path_rewrite
Type
string
Required
optional
Enum
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.
Name
custom_headers
Type
object
Required
optional
Enum
Description
Extra headers sent to the backend. Hop-by-hop and proxy-managed headers (Host, Connection, Transfer-Encoding, etc.) are rejected.
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether the service is enabled
Name
pass_host_header
Type
boolean
Required
optional
Enum
Description
When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
Name
rewrite_redirects
Type
boolean
Required
optional
Enum
Description
When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
Name
auth
Type
object
Required
required
Enum
Description
More Information
Name
password_auth
Type
object
Required
optional
Enum
Description
More Information
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether password auth is enabled
Name
password
Type
string
Required
required
Enum
Description
Auth password
Name
pin_auth
Type
object
Required
optional
Enum
Description
More Information
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether PIN auth is enabled
Name
pin
Type
string
Required
required
Enum
Description
PIN value
Name
bearer_auth
Type
object
Required
optional
Enum
Description
More Information
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether bearer auth is enabled
Name
distribution_groups
Type
string[]
Required
optional
Enum
Description
List of group IDs that can use bearer auth
Name
link_auth
Type
object
Required
optional
Enum
Description
More Information
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether link auth is enabled

Request

POST

/api/reverse-proxies/services

curl -X POST https://api.netbird.io/api/reverse-proxies/services \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "name": {
    "type": "string",
    "description": "Service name"
  },
  "domain": {
    "type": "string",
    "description": "Domain for the service"
  },
  "targets": [
    {
      "target_id": {
        "type": "string",
        "description": "Target ID"
      },
      "target_type": {
        "type": "string",
        "description": "Target type (e.g., \"peer\", \"resource\")",
        "enum": [
          "peer",
          "resource"
        ]
      },
      "path": {
        "type": "string",
        "description": "URL path prefix for this target"
      },
      "protocol": {
        "type": "string",
        "description": "Protocol to use when connecting to the backend",
        "enum": [
          "http",
          "https"
        ]
      },
      "host": {
        "type": "string",
        "description": "Backend ip or domain for this target"
      },
      "port": {
        "type": "integer",
        "description": "Backend port for this target. Use 0 or omit to use the scheme default (80 for http, 443 for https)."
      },
      "enabled": {
        "type": "boolean",
        "description": "Whether this target is enabled"
      },
      "options": {
        "skip_tls_verify": {
          "type": "boolean",
          "description": "Skip TLS certificate verification for this backend"
        },
        "request_timeout": {
          "type": "string",
          "description": "Per-target response timeout as a Go duration string (e.g. \"30s\", \"2m\")"
        },
        "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"
          ]
        },
        "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]*$"
          }
        }
      }
    }
  ],
  "enabled": {
    "type": "boolean",
    "description": "Whether the service is enabled",
    "default": true
  },
  "pass_host_header": {
    "type": "boolean",
    "description": "When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address"
  },
  "rewrite_redirects": {
    "type": "boolean",
    "description": "When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain"
  },
  "auth": {
    "password_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether password auth is enabled"
      },
      "password": {
        "type": "string",
        "description": "Auth password"
      }
    },
    "pin_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether PIN auth is enabled"
      },
      "pin": {
        "type": "string",
        "description": "PIN value"
      }
    },
    "bearer_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether bearer auth is enabled"
      },
      "distribution_groups": [
        {
          "type": "string"
        }
      ]
    },
    "link_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether link auth is enabled"
      }
    }
  }
}'

Response

{
  "id": {
    "type": "string",
    "description": "Service ID"
  },
  "name": {
    "type": "string",
    "description": "Service name"
  },
  "domain": {
    "type": "string",
    "description": "Domain for the service"
  },
  "proxy_cluster": "eu.proxy.netbird.io",
  "targets": [
    {
      "target_id": {
        "type": "string",
        "description": "Target ID"
      },
      "target_type": {
        "type": "string",
        "description": "Target type (e.g., \"peer\", \"resource\")",
        "enum": [
          "peer",
          "resource"
        ]
      },
      "path": {
        "type": "string",
        "description": "URL path prefix for this target"
      },
      "protocol": {
        "type": "string",
        "description": "Protocol to use when connecting to the backend",
        "enum": [
          "http",
          "https"
        ]
      },
      "host": {
        "type": "string",
        "description": "Backend ip or domain for this target"
      },
      "port": {
        "type": "integer",
        "description": "Backend port for this target. Use 0 or omit to use the scheme default (80 for http, 443 for https)."
      },
      "enabled": {
        "type": "boolean",
        "description": "Whether this target is enabled"
      },
      "options": {
        "skip_tls_verify": {
          "type": "boolean",
          "description": "Skip TLS certificate verification for this backend"
        },
        "request_timeout": {
          "type": "string",
          "description": "Per-target response timeout as a Go duration string (e.g. \"30s\", \"2m\")"
        },
        "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"
          ]
        },
        "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]*$"
          }
        }
      }
    }
  ],
  "enabled": {
    "type": "boolean",
    "description": "Whether the service is enabled"
  },
  "pass_host_header": {
    "type": "boolean",
    "description": "When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address"
  },
  "rewrite_redirects": {
    "type": "boolean",
    "description": "When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain"
  },
  "auth": {
    "password_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether password auth is enabled"
      },
      "password": {
        "type": "string",
        "description": "Auth password"
      }
    },
    "pin_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether PIN auth is enabled"
      },
      "pin": {
        "type": "string",
        "description": "PIN value"
      }
    },
    "bearer_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether bearer auth is enabled"
      },
      "distribution_groups": [
        {
          "type": "string"
        }
      ]
    },
    "link_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether link auth is enabled"
      }
    }
  },
  "meta": {
    "created_at": "2024-02-03T10:30:00Z",
    "certificate_issued_at": "2024-02-03T10:35:00Z",
    "status": "active"
  }
}

GET/api/reverse-proxies/clusters

List available proxy clusters

Returns a list of available proxy clusters with their connection status

Request

GET

/api/reverse-proxies/clusters

curl -X GET https://api.netbird.io/api/reverse-proxies/clusters \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

[
  {
    "address": "eu.proxy.netbird.io",
    "connected_proxies": 3
  }
]

GET/api/reverse-proxies/services/{serviceId}

Retrieve a Service

Get information about a specific reverse proxy service

Path Parameters

Name
serviceId
Type
string
Required
required
Enum
Description
The unique identifier of a service

Request

GET

/api/reverse-proxies/services/{serviceId}

curl -X GET https://api.netbird.io/api/reverse-proxies/services/{serviceId} \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

{
  "id": {
    "type": "string",
    "description": "Service ID"
  },
  "name": {
    "type": "string",
    "description": "Service name"
  },
  "domain": {
    "type": "string",
    "description": "Domain for the service"
  },
  "proxy_cluster": "eu.proxy.netbird.io",
  "targets": [
    {
      "target_id": {
        "type": "string",
        "description": "Target ID"
      },
      "target_type": {
        "type": "string",
        "description": "Target type (e.g., \"peer\", \"resource\")",
        "enum": [
          "peer",
          "resource"
        ]
      },
      "path": {
        "type": "string",
        "description": "URL path prefix for this target"
      },
      "protocol": {
        "type": "string",
        "description": "Protocol to use when connecting to the backend",
        "enum": [
          "http",
          "https"
        ]
      },
      "host": {
        "type": "string",
        "description": "Backend ip or domain for this target"
      },
      "port": {
        "type": "integer",
        "description": "Backend port for this target. Use 0 or omit to use the scheme default (80 for http, 443 for https)."
      },
      "enabled": {
        "type": "boolean",
        "description": "Whether this target is enabled"
      },
      "options": {
        "skip_tls_verify": {
          "type": "boolean",
          "description": "Skip TLS certificate verification for this backend"
        },
        "request_timeout": {
          "type": "string",
          "description": "Per-target response timeout as a Go duration string (e.g. \"30s\", \"2m\")"
        },
        "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"
          ]
        },
        "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]*$"
          }
        }
      }
    }
  ],
  "enabled": {
    "type": "boolean",
    "description": "Whether the service is enabled"
  },
  "pass_host_header": {
    "type": "boolean",
    "description": "When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address"
  },
  "rewrite_redirects": {
    "type": "boolean",
    "description": "When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain"
  },
  "auth": {
    "password_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether password auth is enabled"
      },
      "password": {
        "type": "string",
        "description": "Auth password"
      }
    },
    "pin_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether PIN auth is enabled"
      },
      "pin": {
        "type": "string",
        "description": "PIN value"
      }
    },
    "bearer_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether bearer auth is enabled"
      },
      "distribution_groups": [
        {
          "type": "string"
        }
      ]
    },
    "link_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether link auth is enabled"
      }
    }
  },
  "meta": {
    "created_at": "2024-02-03T10:30:00Z",
    "certificate_issued_at": "2024-02-03T10:35:00Z",
    "status": "active"
  }
}

PUT/api/reverse-proxies/services/{serviceId}

Update a Service

Update an existing service

Path Parameters

Name
serviceId
Type
string
Required
required
Enum
Description
The unique identifier of a service

Request-Body Parameters

Name
name
Type
string
Required
required
Enum
Description
Service name
Name
domain
Type
string
Required
required
Enum
Description
Domain for the service
Name
targets
Type
object[]
Required
required
Enum
Description
List of target backends for this service
Name
target_id
Type
string
Required
required
Enum
Description
Target ID
Name
target_type
Type
string
Required
required
Enum
Description
Target type (e.g., "peer", "resource")
Name
path
Type
string
Required
optional
Enum
Description
URL path prefix for this target
Name
protocol
Type
string
Required
required
Enum
Description
Protocol to use when connecting to the backend
Name
host
Type
string
Required
optional
Enum
Description
Backend ip or domain for this target
Name
port
Type
integer
Required
required
Enum
Description
Backend port for this target. Use 0 or omit to use the scheme default (80 for http, 443 for https).
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether this target is enabled
Name
options
Type
object
Required
optional
Enum
Description
More Information
Name
skip_tls_verify
Type
boolean
Required
optional
Enum
Description
Skip TLS certificate verification for this backend
Name
request_timeout
Type
string
Required
optional
Enum
Description
Per-target response timeout as a Go duration string (e.g. "30s", "2m")
Name
path_rewrite
Type
string
Required
optional
Enum
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.
Name
custom_headers
Type
object
Required
optional
Enum
Description
Extra headers sent to the backend. Hop-by-hop and proxy-managed headers (Host, Connection, Transfer-Encoding, etc.) are rejected.
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether the service is enabled
Name
pass_host_header
Type
boolean
Required
optional
Enum
Description
When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
Name
rewrite_redirects
Type
boolean
Required
optional
Enum
Description
When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
Name
auth
Type
object
Required
required
Enum
Description
More Information
Name
password_auth
Type
object
Required
optional
Enum
Description
More Information
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether password auth is enabled
Name
password
Type
string
Required
required
Enum
Description
Auth password
Name
pin_auth
Type
object
Required
optional
Enum
Description
More Information
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether PIN auth is enabled
Name
pin
Type
string
Required
required
Enum
Description
PIN value
Name
bearer_auth
Type
object
Required
optional
Enum
Description
More Information
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether bearer auth is enabled
Name
distribution_groups
Type
string[]
Required
optional
Enum
Description
List of group IDs that can use bearer auth
Name
link_auth
Type
object
Required
optional
Enum
Description
More Information
Name
enabled
Type
boolean
Required
required
Enum
Description
Whether link auth is enabled

Request

PUT

/api/reverse-proxies/services/{serviceId}

curl -X PUT https://api.netbird.io/api/reverse-proxies/services/{serviceId} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "name": {
    "type": "string",
    "description": "Service name"
  },
  "domain": {
    "type": "string",
    "description": "Domain for the service"
  },
  "targets": [
    {
      "target_id": {
        "type": "string",
        "description": "Target ID"
      },
      "target_type": {
        "type": "string",
        "description": "Target type (e.g., \"peer\", \"resource\")",
        "enum": [
          "peer",
          "resource"
        ]
      },
      "path": {
        "type": "string",
        "description": "URL path prefix for this target"
      },
      "protocol": {
        "type": "string",
        "description": "Protocol to use when connecting to the backend",
        "enum": [
          "http",
          "https"
        ]
      },
      "host": {
        "type": "string",
        "description": "Backend ip or domain for this target"
      },
      "port": {
        "type": "integer",
        "description": "Backend port for this target. Use 0 or omit to use the scheme default (80 for http, 443 for https)."
      },
      "enabled": {
        "type": "boolean",
        "description": "Whether this target is enabled"
      },
      "options": {
        "skip_tls_verify": {
          "type": "boolean",
          "description": "Skip TLS certificate verification for this backend"
        },
        "request_timeout": {
          "type": "string",
          "description": "Per-target response timeout as a Go duration string (e.g. \"30s\", \"2m\")"
        },
        "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"
          ]
        },
        "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]*$"
          }
        }
      }
    }
  ],
  "enabled": {
    "type": "boolean",
    "description": "Whether the service is enabled",
    "default": true
  },
  "pass_host_header": {
    "type": "boolean",
    "description": "When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address"
  },
  "rewrite_redirects": {
    "type": "boolean",
    "description": "When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain"
  },
  "auth": {
    "password_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether password auth is enabled"
      },
      "password": {
        "type": "string",
        "description": "Auth password"
      }
    },
    "pin_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether PIN auth is enabled"
      },
      "pin": {
        "type": "string",
        "description": "PIN value"
      }
    },
    "bearer_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether bearer auth is enabled"
      },
      "distribution_groups": [
        {
          "type": "string"
        }
      ]
    },
    "link_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether link auth is enabled"
      }
    }
  }
}'

Response

{
  "id": {
    "type": "string",
    "description": "Service ID"
  },
  "name": {
    "type": "string",
    "description": "Service name"
  },
  "domain": {
    "type": "string",
    "description": "Domain for the service"
  },
  "proxy_cluster": "eu.proxy.netbird.io",
  "targets": [
    {
      "target_id": {
        "type": "string",
        "description": "Target ID"
      },
      "target_type": {
        "type": "string",
        "description": "Target type (e.g., \"peer\", \"resource\")",
        "enum": [
          "peer",
          "resource"
        ]
      },
      "path": {
        "type": "string",
        "description": "URL path prefix for this target"
      },
      "protocol": {
        "type": "string",
        "description": "Protocol to use when connecting to the backend",
        "enum": [
          "http",
          "https"
        ]
      },
      "host": {
        "type": "string",
        "description": "Backend ip or domain for this target"
      },
      "port": {
        "type": "integer",
        "description": "Backend port for this target. Use 0 or omit to use the scheme default (80 for http, 443 for https)."
      },
      "enabled": {
        "type": "boolean",
        "description": "Whether this target is enabled"
      },
      "options": {
        "skip_tls_verify": {
          "type": "boolean",
          "description": "Skip TLS certificate verification for this backend"
        },
        "request_timeout": {
          "type": "string",
          "description": "Per-target response timeout as a Go duration string (e.g. \"30s\", \"2m\")"
        },
        "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"
          ]
        },
        "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]*$"
          }
        }
      }
    }
  ],
  "enabled": {
    "type": "boolean",
    "description": "Whether the service is enabled"
  },
  "pass_host_header": {
    "type": "boolean",
    "description": "When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address"
  },
  "rewrite_redirects": {
    "type": "boolean",
    "description": "When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain"
  },
  "auth": {
    "password_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether password auth is enabled"
      },
      "password": {
        "type": "string",
        "description": "Auth password"
      }
    },
    "pin_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether PIN auth is enabled"
      },
      "pin": {
        "type": "string",
        "description": "PIN value"
      }
    },
    "bearer_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether bearer auth is enabled"
      },
      "distribution_groups": [
        {
          "type": "string"
        }
      ]
    },
    "link_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether link auth is enabled"
      }
    }
  },
  "meta": {
    "created_at": "2024-02-03T10:30:00Z",
    "certificate_issued_at": "2024-02-03T10:35:00Z",
    "status": "active"
  }
}

DELETE/api/reverse-proxies/services/{serviceId}

Delete a Service

Delete an existing service

Path Parameters

Name
serviceId
Type
string
Required
required
Enum
Description
The unique identifier of a service

Request

DELETE

/api/reverse-proxies/services/{serviceId}

curl -X DELETE https://api.netbird.io/api/reverse-proxies/services/{serviceId} \
-H 'Authorization: Token <TOKEN>'

GET/api/reverse-proxies/domains

Retrieve Service Domains

Get information about domains that can be used for service endpoints.

Request

GET

/api/reverse-proxies/domains

curl -X GET https://api.netbird.io/api/reverse-proxies/domains \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'

Response

[
  {
    "id": {
      "type": "string",
      "description": "Domain ID"
    },
    "domain": {
      "type": "string",
      "description": "Domain name"
    },
    "validated": {
      "type": "boolean",
      "description": "Whether the domain has been validated"
    },
    "type": "free",
    "target_cluster": {
      "type": "string",
      "description": "The proxy cluster this domain is validated against (only for custom domains)"
    }
  }
]

POST/api/reverse-proxies/domains

Create a Custom domain

Create a new Custom domain for use with service endpoints, this will trigger an initial validation check

Request-Body Parameters

Name
domain
Type
string
Required
required
Enum
Description
Domain name
Name
target_cluster
Type
string
Required
required
Enum
Description
The proxy cluster this domain should be validated against

Request

POST

/api/reverse-proxies/domains

curl -X POST https://api.netbird.io/api/reverse-proxies/domains \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "domain": {
    "type": "string",
    "description": "Domain name"
  },
  "target_cluster": {
    "type": "string",
    "description": "The proxy cluster this domain should be validated against"
  }
}'

Response

{
  "id": {
    "type": "string",
    "description": "Service ID"
  },
  "name": {
    "type": "string",
    "description": "Service name"
  },
  "domain": {
    "type": "string",
    "description": "Domain for the service"
  },
  "proxy_cluster": "eu.proxy.netbird.io",
  "targets": [
    {
      "target_id": {
        "type": "string",
        "description": "Target ID"
      },
      "target_type": {
        "type": "string",
        "description": "Target type (e.g., \"peer\", \"resource\")",
        "enum": [
          "peer",
          "resource"
        ]
      },
      "path": {
        "type": "string",
        "description": "URL path prefix for this target"
      },
      "protocol": {
        "type": "string",
        "description": "Protocol to use when connecting to the backend",
        "enum": [
          "http",
          "https"
        ]
      },
      "host": {
        "type": "string",
        "description": "Backend ip or domain for this target"
      },
      "port": {
        "type": "integer",
        "description": "Backend port for this target. Use 0 or omit to use the scheme default (80 for http, 443 for https)."
      },
      "enabled": {
        "type": "boolean",
        "description": "Whether this target is enabled"
      },
      "options": {
        "skip_tls_verify": {
          "type": "boolean",
          "description": "Skip TLS certificate verification for this backend"
        },
        "request_timeout": {
          "type": "string",
          "description": "Per-target response timeout as a Go duration string (e.g. \"30s\", \"2m\")"
        },
        "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"
          ]
        },
        "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]*$"
          }
        }
      }
    }
  ],
  "enabled": {
    "type": "boolean",
    "description": "Whether the service is enabled"
  },
  "pass_host_header": {
    "type": "boolean",
    "description": "When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address"
  },
  "rewrite_redirects": {
    "type": "boolean",
    "description": "When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain"
  },
  "auth": {
    "password_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether password auth is enabled"
      },
      "password": {
        "type": "string",
        "description": "Auth password"
      }
    },
    "pin_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether PIN auth is enabled"
      },
      "pin": {
        "type": "string",
        "description": "PIN value"
      }
    },
    "bearer_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether bearer auth is enabled"
      },
      "distribution_groups": [
        {
          "type": "string"
        }
      ]
    },
    "link_auth": {
      "enabled": {
        "type": "boolean",
        "description": "Whether link auth is enabled"
      }
    }
  },
  "meta": {
    "created_at": "2024-02-03T10:30:00Z",
    "certificate_issued_at": "2024-02-03T10:35:00Z",
    "status": "active"
  }
}

DELETE/api/reverse-proxies/domains/{domainId}

Delete a Custom domain

Delete an existing service custom domain

Path Parameters

Name
domainId
Type
string
Required
required
Enum
Description
The custom domain ID

Request

DELETE

/api/reverse-proxies/domains/{domainId}

curl -X DELETE https://api.netbird.io/api/reverse-proxies/domains/{domainId} \
-H 'Authorization: Token <TOKEN>'

GET/api/reverse-proxies/domains/{domainId}/validate

Validate a custom domain

Trigger domain ownership validation for a custom domain

Path Parameters

Name
domainId
Type
string
Required
required
Enum
Description
The custom domain ID

Request

GET

/api/reverse-proxies/domains/{domainId}/validate

curl -X GET https://api.netbird.io/api/reverse-proxies/domains/{domainId}/validate \
-H 'Authorization: Token <TOKEN>'