Skip to main content

Account-Based Discovery

Account-Based Discovery enables nodes registered to the same account to discover each other globally, regardless of network location.

Prerequisites​

Account-based discovery 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.

Overview​

AttributeValue
ScopeGlobal (across any network)
Cloud dependencyRequires mDS (mimik Discovery Service)
CommunicationTunneled (HTTP only)
CapabilitiesHTTP RESTful APIs

How It Works​

Account-Based Discovery uses mDS (mimik Discovery Service) as a registry for nodes associated with each account.

  1. Registration: Each node registers with mDS using an account-scoped access token. Registration includes node ID, available services, and capabilities.

  2. Discovery: When a node needs to find other nodes on the same account, it queries mDS, which returns a list of all registered nodes for that account.

  3. Communication: Nodes on different networks communicate through the Tunneling Service, which handles NAT traversal.

API Usage​

Account-based discovery requires a stored JWT. First, store your access token with the Insight API:

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
  }'

Then discover nodes across your account:

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/nodes?type=account" \
  -H "Authorization: Bearer $API_KEY"

Response (200 OK)

{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "accountId": "acct-123456",
      "name": "Office Workstation",
      "os": "linux",
      "addresses": [
        {
          "type": "local",
          "url": { "href": "http://10.0.1.50:8083" }
        }
      ],
      "services": []
    }
  ]
}

Nodes on different networks communicate through tunneling. Use the SEP endpoint to route requests to a remote node:

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

See Insight API: Tunneling via SEP for the full routing workflow.

Use Cases​

  • Personal node mesh: Your phone finding your tablet on a different network
  • Cross-node sync: Data synchronization between your nodes
  • Remote access: Accessing your home node from anywhere
  • Distributed AI: AI agents collaborating across your nodes

Requirements​

  • Internet connectivity for mDS queries
  • Account-scoped access token for each node
  • All nodes registered under the same account

Limitations​

  • Requires internet connectivity for discovery
  • HTTP only for cross-network communication (no WebSocket/SSE yet)
  • Higher latency than Link Local due to tunneling
  • Cannot discover nodes from other accounts

If your nodes happen to be on the same network, they will automatically use Link Local Discovery for direct communication with full protocol support.