Auth Network Client

This endpoint is used to authenticate an existing client device or register a new one into your network. It returns a specific JWT for the client device (by_client_jwt) and optional proxy or relay configuration in proxy_config_result.

`POST /network/auth-client`

Register or authenticate a network client. For new devices, you can provide a description and hardware specification. You can also request proxy, HTTPS auth, WireGuard, IP locking, and an initial device state via proxy_config.

Request

POST /network/auth-client

Headers:

{
  "Host": "api.bringyour.com",
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_JWT_TOKEN"
}

Body:

{
  "client_id": "string",
  "source_client_id": "string",
  "derived_client_id": "string",
  "description": "My Laptop",
  "device_spec": "macOS-arm64-v1.0.0",
  "proxy_config": {
    "lock_caller_ip": true,
    "lock_ip_list": [
      "203.0.113.10"
    ],
    "https_require_auth": true,
    "enable_wg": true,
    "initial_device_state": {
      "country_code": "US",
      "location": {
        "connect_location_id": {
          "client_id": "string",
          "location_id": "string",
          "location_group_id": "string",
          "best_available": true
        },
        "name": "United States",
        "location_type": "country"
      },
      "performance_profile": {
        "window_type": "quality",
        "window_size_settings": {
          "window_size_min": 0,
          "window_size_min_p2p_only": 0,
          "window_size_max": 0,
          "window_size_hard_max": 0,
          "window_size_reconnect_scale": 0,
          "keep_healthiest_count": 0,
          "ulimit": 0
        }
      }
    }
  }
}

Fields

Field	Type	Description
`client_id`	`string`	Optional. UDID of an existing client. Omit to register a new device.
`source_client_id`	`string`	Optional. The source client identifier for ancillary or derived clients.
`derived_client_id`	`string`	Optional. Identifier for a client derived from `source_client_id` where applicable.
`description`	`string`	Optional. Sets the device name if this is a new registration.
`device_spec`	`string`	Optional. Hardware or software specification identifier for the device.
`proxy_config`	`object`	Optional. Configuration for proxy behavior, including IP locking, HTTPS auth, WireGuard, and an initial device state.
`proxy_config.lock_caller_ip`	`boolean`	Optional. If true, locks access to the caller IP observed by the API.
`proxy_config.lock_ip_list`	`string[]`	Optional. Explicit allow-list of IPs permitted to use the proxy.
`proxy_config.https_require_auth`	`boolean`	Optional. If true, HTTPS proxy requires auth credentials/token.
`proxy_config.enable_wg`	`boolean`	Optional. If true, includes WireGuard configuration in the response.
`proxy_config.initial_device_state`	`object`	Optional. Sets initial country, location selection, and performance profile hints.
`proxy_config.initial_device_state.country_code`	`string`	Optional. Two-letter country code.
`proxy_config.initial_device_state.location`	`object`	Optional. Desired initial location selection.
`proxy_config.initial_device_state.location.connect_location_id`	`object`	Optional. Specific location identity fields; set `best_available` to true to auto-pick.
`proxy_config.initial_device_state.location.name`	`string`	Optional. Human-readable location name.
`proxy_config.initial_device_state.location.location_type`	`string`	Optional. Location type, for example `country`.
`proxy_config.initial_device_state.performance_profile`	`object`	Optional. Performance profile settings for connection selection behavior.
`proxy_config.initial_device_state.performance_profile.window_type`	`string`	Optional. Window strategy, for example `quality`.
`proxy_config.initial_device_state.performance_profile.window_size_settings`	`object`	Optional. Window sizing values controlling connection selection and health.

Response

`200 Success`

Status: 200 OK
Content-Type: application/json

{
  "by_client_jwt": "string",
  "proxy_config_result": {
    "keepalive_seconds": 0,
    "http_proxy_url": "string",
    "https_proxy_url": "string",
    "socks_proxy_url": "string",
    "auth_token": "string",
    "instance_id": "string",
    "proxy_host": "string",
    "socks_proxy_port": 0,
    "http_proxy_port": 0,
    "https_proxy_port": 0,
    "wg_config": {
      "wg_proxy_port": 0,
      "client_private_key": "string",
      "client_public_key": "string",
      "client_ipv4": "string",
      "proxy_public_key": "string",
      "config": "string"
    }
  },
  "error": {
    "client_limit_exceeded": true,
    "message": "string"
  }
}

Fields

Field	Type	Description
`by_client_jwt`	`string`	The authentication token specific to this client device.
`proxy_config_result`	`object`	Resulting network configuration for the client, including proxy URLs, ports, and optional WireGuard config.
`proxy_config_result.keepalive_seconds`	`number`	Keepalive interval (seconds) for maintaining the session.
`proxy_config_result.http_proxy_url`	`string`	HTTP proxy URL if issued.
`proxy_config_result.https_proxy_url`	`string`	HTTPS proxy URL if issued.
`proxy_config_result.socks_proxy_url`	`string`	SOCKS proxy URL if issued.
`proxy_config_result.auth_token`	`string`	Token used for authenticating to proxy endpoints when required.
`proxy_config_result.instance_id`	`string`	Proxy instance identifier.
`proxy_config_result.proxy_host`	`string`	Proxy host address.
`proxy_config_result.socks_proxy_port`	`number`	SOCKS proxy port.
`proxy_config_result.http_proxy_port`	`number`	HTTP proxy port.
`proxy_config_result.https_proxy_port`	`number`	HTTPS proxy port.
`proxy_config_result.wg_config`	`object`	WireGuard configuration, present when `proxy_config.enable_wg` is true.
`error`	`object`	Present if authentication or registration failed.
`error.client_limit_exceeded`	`boolean`	True if the network has reached its maximum device limit.

Example

HTTP Request

POST /network/auth-client HTTP/1.1
Host: api.bringyour.com
Content-Type: application/json
Authorization: Bearer YOUR_JWT_TOKEN
 
{
  "description": "Office Desktop",
  "device_spec": "linux-x64-deb",
  "proxy_config": {
    "enable_wg": true,
    "https_require_auth": true,
    "lock_caller_ip": true
  }
}

Successful HTTP Response

{
  "by_client_jwt": "eyJhbGciOiJIUzI1NiI...",
  "proxy_config_result": {
    "keepalive_seconds": 300,
    "http_proxy_url": "http://proxy.example:8080",
    "https_proxy_url": "https://proxy.example:8443",
    "socks_proxy_url": "socks5://proxy.example:1080",
    "auth_token": "token...",
    "instance_id": "instance...",
    "proxy_host": "proxy.example",
    "socks_proxy_port": 1080,
    "http_proxy_port": 8080,
    "https_proxy_port": 8443,
    "wg_config": {
      "wg_proxy_port": 51820,
      "client_private_key": "...",
      "client_public_key": "...",
      "client_ipv4": "10.0.0.2/32",
      "proxy_public_key": "...",
      "config": "..."
    }
  },
  "error": null
}

On this page

Auth Network Client

POST /network/auth-client

Request

Fields

Response

200 Success

Fields

Example

HTTP Request

Successful HTTP Response

`POST /network/auth-client`

`200 Success`