NetBird Full API Reference + Read-Only MCP Prototype
POST/api/reverse-proxies/services

Create a reverse proxy service

Creates a reverse proxy service with the specified domain, enabled state, and service configuration. Supply name, domain, and enabled; configure mode and targets to define how requests reach the backends. A 200 response returns the created service object.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

12 body fields

JSON configuration for a reverse proxy service. Supply name, domain, and enabled; the remaining fields configure access, routing, and backend targets.

access_groupsarray<string>optional
NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
access_restrictionsobjectoptional
Connection-level access restrictions based on IP address or geography. Applies to both HTTP and L4 services.
authobjectoptional
Authentication configuration for the service, including bearer, header, link, password, or PIN authentication.
domainstringrequired
Domain for the service
enabledbooleanrequired
Whether the service is enabled
Default:true
listen_portintegeroptional
Port the proxy listens on (L4/TLS only). Set to 0 for auto-assignment.
modestringoptional
Service mode. "http" for L7 reverse proxy, "tcp"/"udp"/"tls" for L4 passthrough.
Allowed:httptcpudptlsDefault:http
namestringrequired
Service name
pass_host_headerbooleanoptional
When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
privatebooleanoptional
When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
Default:false
rewrite_redirectsbooleanoptional
When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
targetsarray<object>optional
List of target backends for this service

6 status codes
200Returns the created service object, including its identifier, name, domain, targets, enabled status, authentication configuration, and metadata.
access_groupsarray<string>optional
NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
access_restrictionsobjectoptional
Connection-level access restrictions based on IP address or geography. Applies to both HTTP and L4 services.
authobjectrequired
domainstringrequired
Domain for the service
enabledbooleanrequired
Whether the service is enabled
idstringrequired
Service ID
listen_portintegeroptional
Port the proxy listens on (L4/TLS only)
metaobjectrequired
modestringoptional
Service mode. "http" for L7 reverse proxy, "tcp"/"udp"/"tls" for L4 passthrough.
Allowed:httptcpudptlsDefault:http
namestringrequired
Service name
pass_host_headerbooleanoptional
When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
port_auto_assignedbooleanoptional
Whether the listen port was auto-assigned
privatebooleanoptional
When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
Default:false
proxy_clusterstringoptional
The proxy cluster handling this service (derived from domain)
rewrite_redirectsbooleanoptional
When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
targetsarray<object>required
List of target backends for this service
terminatedbooleanoptional
Whether the service has been terminated. Terminated services cannot be updated. Services that violate the Terms of Service will be terminated.
400Returned when the request is invalid or a service field fails validation.
401Returned when the request lacks authentication.
403Returned when the authenticated user is forbidden from creating a service.
409Returned when creating the service conflicts with an existing resource or configuration.
messagestringoptional
A human-readable error message.
500Returned when an internal server error occurs.

Error handling

A 400 is returned when required fields are missing or a value fails validation; a 401 indicates missing authentication, a 403 indicates forbidden access, a 409 indicates a conflict, and a 500 indicates an internal server error. name, domain, and enabled are required; mode must be http, tcp, udp, or tls, and target protocol, target_type, and port values must satisfy their declared schema constraints. When private is true, mode must be http and access_groups must be provided; access_groups cannot be combined with bearer authentication.