OrbConnect Endpoints
OrbConnect (OpenConnect-compatible) protocol tunnel management including DTLS transport, FIPS mode, and traffic mimicry on OrbMesh servers.
Connect (Client)
Establishes an OrbConnect tunnel connection. Returns server address, allocated IP addresses (IPv4 and IPv6), DTLS configuration, and optional FIPS and mimicry settings.
/orbconnect/connectEstablish an OrbConnect tunnel with DTLS transport, FIPS compliance, and traffic mimicry
Device Token Required
This endpoint requires a device token obtained from OrbNET's device authorization flow. See the OrbMesh Authentication section for details.
When to Use OrbConnect
OrbConnect is based on the OpenConnect protocol and is highly compatible with enterprise firewalls and corporate networks. It supports DTLS for high-performance transport, FIPS 140-2 compliant ciphers for government and regulated environments, and traffic mimicry to disguise connections as Microsoft Teams, Google, or other services.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
fipsEnabled | boolean | Optional | Enable FIPS 140-2 compliant ciphers. Required for government and regulated environments. Defaults to the server's global FIPS setting. |
mimicry | string | Optional | Traffic mimicry profile. Disguises the tunnel as legitimate service traffic. Options: "none", "teams" (Microsoft Teams), "google" (Google services). Defaults to "none". |
Code Examples
curl -X POST https://198.51.100.1:8443/orbconnect/connect \
-H "Authorization: Bearer DEVICE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"fipsEnabled": false,
"mimicry": "teams"
}'Response
{
"success": true,
"serverAddr": "198.51.100.1",
"serverPort": 443,
"dtlsPort": 443,
"display_name": "user@example.com",
"password": "session_password_abc123",
"allocatedIPv4": "10.10.0.42",
"allocatedIPv6": "fd00::2a",
"fipsEnabled": false,
"ipv6Enabled": true,
"mtu": 1500,
"dns": ["10.10.0.1", "1.1.1.1"],
"dtlsCiphers": ["TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256"],
"gatewayIPv4": "10.10.0.1",
"gatewayIPv6": "fd00::1"
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired device token"
}
}Response Fields
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the connection was established |
serverAddr | string | Server IP address for the OrbConnect connection |
serverPort | integer | CSTP (TLS) port, typically 443 |
dtlsPort | integer | DTLS port for high-performance UDP transport, typically 443 |
display_name | string | Display name for the session (usually the user's email) |
password | string | Session password for the OrbConnect handshake |
allocatedIPv4 | string | Assigned IPv4 tunnel address |
allocatedIPv6 | string | Assigned IPv6 tunnel address (if IPv6 is enabled) |
fipsEnabled | boolean | Whether FIPS 140-2 ciphers are active for this session |
ipv6Enabled | boolean | Whether IPv6 is available on this server |
mtu | integer | Maximum Transmission Unit (default 1500) |
dns | string[] | DNS servers to configure on the tunnel interface |
dtlsCiphers | string[] | Supported DTLS cipher suites for this session |
gatewayIPv4 | string | IPv4 gateway address for the tunnel |
gatewayIPv6 | string | IPv6 gateway address for the tunnel |
DTLS vs. CSTP
OrbConnect uses two transport layers: CSTP (TLS over TCP) for the control channel and initial data, and DTLS (TLS over UDP) for high-performance data transport. The client should attempt DTLS first and fall back to CSTP if UDP is blocked.
Disconnect (Client)
Terminates an active OrbConnect session and releases the allocated IP addresses.
/orbconnect/disconnectDisconnect the current OrbConnect tunnel and release allocated IPs
Code Examples
curl -X POST https://198.51.100.1:8443/orbconnect/disconnect \
-H "Authorization: Bearer DEVICE_TOKEN"Response
{
"success": true,
"message": "Disconnected successfully"
}Server Status (Internal)
Returns the current OrbConnect service status, including FIPS mode, IPv6 support, and active session count.
/orbconnect/statusGet OrbConnect server status including FIPS and session information
Internal Endpoint
This endpoint is called by OrbNET for server monitoring and orchestration. It is not intended for client applications.
Code Examples
curl -X GET https://198.51.100.1:8443/orbconnect/status \
-H "X-API-Key: INTERNAL_API_KEY"Response
{
"success": true,
"enabled": true,
"running": true,
"serverAddr": "198.51.100.1",
"listenPort": 443,
"dtlsPort": 443,
"fipsEnabled": false,
"ipv6Enabled": true,
"sessionCount": 24
}IP Mode Tunnel
Establishes the OrbConnect IP-mode tunnel for data transport. This endpoint handles the actual tunnel data flow after a connection has been established via /orbconnect/connect.
/orbconnect/tunnelOrbConnect IP-mode tunnel for encapsulated data transport
Code Examples
# The OrbConnect tunnel is typically used by OrbVPN client apps.
curl -X POST https://198.51.100.1:8443/orbconnect/tunnel \
-H "Authorization: Bearer DEVICE_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @tunnel_payload.binBridge Tunnel (Server-to-Server)
Handles server-to-server tunnel relay for bridge (multi-hop) mode. When a client connects to a bridge entry server, the entry server uses this endpoint to forward traffic to the exit server.
/orbconnect/bridge-tunnelServer-to-server bridge tunnel relay for multi-hop connections
Bridge Mode
In bridge mode, the client connects to an entry server, which then relays traffic to an exit server via this endpoint. This provides an additional layer of privacy and can help bypass regional blocking. See the Bridge Mode API for details on establishing bridge connections.
Code Examples
# Bridge relay: entry server forwards to exit server
curl -X POST https://203.0.113.50:8443/orbconnect/bridge-tunnel \
-H "X-API-Key: BRIDGE_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @relay_payload.binAdd Session (Internal)
Creates an OrbConnect session on the server. Called by OrbNET during user provisioning.
/orbconnect/add-sessionCreate an OrbConnect session on the server (called by OrbNET)
Internal Management Endpoint
This endpoint is called exclusively by OrbNET for session lifecycle management. Client applications should use /orbconnect/connect instead.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
userUuid | string | Required | The unique user identifier from OrbNET. |
display_name | string | Required | Display name for the session, typically the user's email. |
fipsEnabled | boolean | Optional | Enable FIPS 140-2 compliant ciphers for this session. |
mimicry | string | Optional | Traffic mimicry profile: "none", "teams", or "google". |
Code Examples
curl -X POST https://198.51.100.1:8443/orbconnect/add-session \
-H "X-API-Key: INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userUuid": "usr_abc123",
"display_name": "user@example.com",
"fipsEnabled": false,
"mimicry": "none"
}'Response
{
"success": true,
"message": "Session created successfully"
}Remove Session (Internal)
Removes an OrbConnect session from the server and terminates the connection. Called by OrbNET during session cleanup.
/orbconnect/remove-sessionRemove an OrbConnect session from the server (called by OrbNET)
Internal Management Endpoint
This endpoint is called exclusively by OrbNET. Client applications should use /orbconnect/disconnect instead.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
userUuid | string | Required | The unique user identifier whose session should be removed. |
Code Examples
curl -X POST https://198.51.100.1:8443/orbconnect/remove-session \
-H "X-API-Key: INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userUuid": "usr_abc123"
}'Response
{
"success": true,
"message": "Session removed successfully"
}Related Endpoints
- Health & Monitoring -- Server health and protocol status
- WireGuard -- WireGuard tunnel management
- VLESS -- VLESS protocol endpoints
- Bridge Mode -- Multi-hop bridge connections
- Protocol Mimicry -- Traffic disguise profiles