Bridge Mode Endpoints

Multi-hop bridge connections for enhanced privacy and censorship bypass, routing traffic through entry and exit VPN servers.

Overview

Bridge mode (multi-hop) routes VPN traffic through two servers: an entry server (bridge) and an exit server. The client connects to the entry server, which forwards traffic to the exit server. This provides an additional layer of privacy (the exit server only sees the entry server's IP, not the client's) and helps bypass censorship by using an entry server in a less restricted location.

How Bridge Mode Works

  1. The client connects to the entry server (bridge server) using any supported protocol.
  2. The entry server establishes a server-to-server tunnel to the exit server.
  3. All client traffic is relayed: Client -> Entry Server -> Exit Server -> Internet.
  4. The exit server sees the entry server's IP, not the client's real IP.
  5. Neither server alone has both the client's identity and their destination traffic.

When to Use Bridge Mode

Bridge mode is recommended by SmartConnect when direct connections to exit servers are unreliable due to IP blocking or censorship. It is especially effective when the entry server is in a region with unrestricted internet access.

Connect (Establish Bridge)

Establishes a bridge (multi-hop) connection through the entry server to the specified exit server. The entry server negotiates the exit tunnel and returns connection details for all supported protocols on the exit server.

POST/bridge/connect

Establish a multi-hop bridge connection through this entry server to an exit server

Authentication:Bearer Token

Request Parameters

ParameterTypeRequiredDescription
exit_server_idstring RequiredThe target exit server identifier. Obtained from the OrbNET Servers API.
protocolstring RequiredVPN protocol to use for the bridge tunnel: "wireguard", "vless", or "orbconnect".
mimicrystringOptionalTraffic mimicry profile for the entry-to-exit tunnel: "teams", "google", "none", etc. Defaults to "none".
user_uuidstring RequiredThe user's unique identifier for session tracking.
wireguard_public_keystringOptionalClient's WireGuard public key. Required when protocol is "wireguard".

Code Examples 

curl -X POST https://198.51.100.1:8443/bridge/connect \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exit_server_id": "srv_us_ny_02",
    "protocol": "vless",
    "mimicry": "teams",
    "user_uuid": "usr_abc123"
  }'

Response

200Bridge connection established successfully
{
  "session_id": "brg_sess_xyz789",
  "bridge_server_id": "srv_eu_de_01",
  "exit_server_id": "srv_us_ny_02",
  "protocol": "vless",
  "status": "connected",
  "exit_server_wireguard": {
    "serverPublicKey": "xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=",
    "endpoint": "203.0.113.50:51820",
    "assignedIP": "10.8.0.42/32"
  },
  "exit_server_vless": {
    "vlessUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "serverEndpoint": "203.0.113.50",
    "serverPort": 8443,
    "realityPublicKey": "LS0tLS1CRUdJTi...",
    "realitySNI": "www.microsoft.com"
  },
  "exit_server_orbconnect": {
    "serverAddr": "203.0.113.50",
    "serverPort": 443,
    "dtlsPort": 443,
    "password": "session_password_xyz"
  }
}
401Invalid or expired device token
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired device token"
  }
}
502Exit server unreachable
{
  "success": false,
  "error": {
    "code": "EXIT_SERVER_UNREACHABLE",
    "message": "Unable to establish tunnel to exit server srv_us_ny_02"
  }
}

Response Fields

FieldTypeDescription
session_idstringUnique bridge session identifier for status queries and disconnect
bridge_server_idstringEntry (bridge) server identifier
exit_server_idstringExit server identifier
protocolstringProtocol used for the bridge tunnel
statusstringSession status: connected, connecting, failed
exit_server_wireguardobjectWireGuard connection details on the exit server (if available)
exit_server_vlessobjectVLESS connection details on the exit server (if available)
exit_server_orbconnectobjectOrbConnect connection details on the exit server (if available)

Multi-Protocol Response

The bridge connect response includes connection details for all available protocols on the exit server, regardless of which protocol was selected for the bridge tunnel itself. This allows the client to use different protocols for the client-to-bridge and bridge-to-exit segments.

Get Bridge Session Status

Returns the current status of a bridge session, including traffic statistics and connection health.

GET/bridge/status

Get the current status of a bridge session

Authentication:Bearer Token

Query Parameters

ParameterTypeRequiredDescription
session_idstringOptionalThe bridge session ID returned from /bridge/connect. Either session_id or user_id is required.
user_idstringOptionalThe user UUID to look up their active bridge session. Either session_id or user_id is required.

Code Examples 

# Query by session ID
curl -X GET "https://198.51.100.1:8443/bridge/status?session_id=brg_sess_xyz789" \
  -H "Authorization: Bearer DEVICE_TOKEN"

# Query by user ID
curl -X GET "https://198.51.100.1:8443/bridge/status?user_id=usr_abc123" \
  -H "Authorization: Bearer DEVICE_TOKEN"

Response

200Bridge session status
{
  "session_id": "brg_sess_xyz789",
  "user_id": "usr_abc123",
  "protocol": "vless",
  "bridge_server_id": "srv_eu_de_01",
  "exit_server_id": "srv_us_ny_02",
  "status": "connected",
  "created_at": "2026-02-08T14:00:00Z",
  "last_activity": "2026-02-08T14:32:15Z",
  "bytes_sent": 15728640,
  "bytes_received": 52428800
}
404No active bridge session found
{
  "success": false,
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "No active bridge session found for the specified ID"
  }
}

Response Fields

FieldTypeDescription
session_idstringBridge session identifier
user_idstringUser UUID
protocolstringProtocol used for the bridge tunnel
bridge_server_idstringEntry (bridge) server identifier
exit_server_idstringExit server identifier
statusstringSession status: connected, disconnecting, disconnected
created_atstringISO 8601 timestamp of session creation
last_activitystringISO 8601 timestamp of last traffic through the bridge
bytes_sentintegerTotal bytes sent through the bridge (client to exit)
bytes_receivedintegerTotal bytes received through the bridge (exit to client)

Disconnect Bridge

Terminates an active bridge session and closes both the client-to-entry and entry-to-exit tunnels.

POST/bridge/disconnect

Disconnect an active bridge session and close all associated tunnels

Authentication:Bearer Token

Request Parameters

ParameterTypeRequiredDescription
session_idstringOptionalThe bridge session ID to disconnect. Either session_id or user_id is required.
user_idstringOptionalDisconnect all bridge sessions for this user UUID. Either session_id or user_id is required.

Code Examples 

# Disconnect by session ID
curl -X POST https://198.51.100.1:8443/bridge/disconnect \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "brg_sess_xyz789"}'

# Disconnect all sessions for a user
curl -X POST https://198.51.100.1:8443/bridge/disconnect \
  -H "Authorization: Bearer DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_abc123"}'

Response

200Bridge session disconnected
{
  "success": true,
  "message": "Bridge session disconnected"
}

Bridge Service Health

Returns the health status of the bridge service, including active session count and average relay latency. This is a public endpoint for monitoring.

GET/bridge/health

Get the health status of the bridge relay service

Authentication:No Auth Required

Public Endpoint

The bridge health endpoint requires no authentication. It is designed for monitoring systems and load balancers to assess bridge service availability.

Code Examples 

curl -X GET https://198.51.100.1:8443/bridge/health

Response

200Bridge service health information
{
  "status": "healthy",
  "enabled": true,
  "active_sessions": 47,
  "total_sessions": 12834,
  "active_tunnels": 94,
  "avg_latency_ms": 23.4,
  "uptime": "72h15m42s"
}

Response Fields

FieldTypeDescription
statusstringBridge service health: healthy, degraded, or unhealthy
enabledbooleanWhether bridge mode is enabled on this server
active_sessionsintegerNumber of currently active bridge sessions
total_sessionsintegerTotal bridge sessions since last restart
active_tunnelsintegerNumber of active entry-to-exit tunnels (typically 2x active_sessions)
avg_latency_msnumberAverage relay latency in milliseconds
uptimestringBridge service uptime since last restart

Bridge Latency

Bridge mode adds relay latency because traffic must traverse an additional server hop. The avg_latency_ms field indicates the current relay overhead. For latency-sensitive applications, consider using direct connections when possible and reserve bridge mode for censored environments where direct connections are unreliable.

Related Endpoints

  • Smart Connect -- Bridge recommendations based on network analysis
  • WireGuard -- WireGuard tunnel management (supports bridge via exitServerId)
  • VLESS -- VLESS protocol endpoints (supports bridge relay)
  • OrbConnect -- OrbConnect tunnel management (includes /orbconnect/bridge-tunnel)
  • Protocol Mimicry -- Traffic disguise for bridge tunnels
  • Health & Monitoring -- Server health and protocol status

Smart Connect Endpoints

Previous Page

Protocol Mimicry Endpoints

Next Page

On this page

Overview
Connect (Establish Bridge)
Request Parameters
Code Examples
Response
Response Fields
Get Bridge Session Status
Query Parameters
Code Examples
Response
Response Fields
Disconnect Bridge
Request Parameters
Code Examples
Response
Bridge Service Health
Code Examples
Response
Response Fields
Related Endpoints