Skip to main content
Version: 3.20.0 (stable)

Tunneling Service

The Tunneling Service enables nodes to communicate across different networks, even when behind NAT/firewalls. This is essential for Account-Based and Proximity Discovery, where nodes on different networks need to reach each other.

Prerequisites​

Tunneling requires a developer account and account association:

  1. Developer Console: Create a project and get your Client ID and Developer ID Token
  2. Account Association: Associate your mimOE node with your developer account to obtain an access token

The access token from account association is what you store via PUT /token in the API usage below.

Tunnel Types​

mimOE provides two types of tunnels for optimized cross-network communication.

SEP (Signaling Endpoint)​

SEP is established on a proxy node selected by the supernode (typically the supernode itself). Instead of each node in the local mesh establishing its own tunnel, a single SEP enables all local nodes to be reachable from outside the network.

Characteristics:

  • One tunnel serves the entire local mesh
  • Reduces overhead by eliminating per-node tunnel establishment
  • Proxy node routes requests to the appropriate local node
  • Optimization unique to mimOE architecture

BEP (Bearer Endpoint)​

When a particular node requires dedicated communication, a mim can request a BEP (a direct tunnel that bypasses the SEP entirely).

Characteristics:

  • Established on-demand for heavy communication scenarios
  • Direct connection between specific nodes
  • Avoids routing through the proxy node
  • Better performance for sustained traffic

Typical Request Flow​

  1. A requesting mim discovers another mim on a different network via discovery service
  2. The requesting mim uses SEP to reach the target mim through the proxy node
  3. The requesting mim authenticates with the target mim
  4. For heavy traffic, the requesting mim asks the target mim to establish a BEP
  5. Subsequent communication uses BEP directly

API Usage​

Tunneling uses the Insight API to get the SEP routing information, then includes routing headers when calling a remote node.

Step 1: Store a JWT​

Tunneling requires an account-scoped token:

curl -X PUT "http://localhost:8083/mimik-mesh/insight/v1/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "expiresAt": 1729677600
  }'

Step 2: Get SEP Info​

Retrieve the service endpoint for cross-network routing:

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/info?types=sep" \
  -H "Authorization: Bearer $API_KEY"

Response (200 OK)

{
  "data": {
    "sep": {
      "nodeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "url": "https://sep.mimik.com",
      "headers": {
        "x-mimik-port": "8083",
        "x-mimik-routing": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "status": "available"
    }
  }
}

Step 3: Call a Remote Node​

Use the SEP url as the base and include the routing headers to reach a mim on the remote node:

curl -X GET "https://sep.mimik.com/my-agent/v1/data" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-mimik-port: 8083" \
  -H "x-mimik-routing: a1b2c3d4-e5f6-7890-abcd-ef1234567890"

This routes the request through the mimik cloud relay to the target node, where it is forwarded to the local mim at /my-agent/v1/data.

See the Insight API reference for full details.

Security​

  • Transport encryption: All tunnel connections use TLS (HTTPS)
  • Node authentication: Only registered nodes can establish tunnels
  • Request authentication: Requests include signed tokens
  • Account isolation: Cross-account tunneling only for public services