OmniEdge Client API Reference

This document provides a comprehensive reference for the OmniEdge Backend API, specifically tailored for developers building Clients, Agents, Robotics Integrations, and Headless Daemons.

1. Authentication

OmniEdge supports two primary authentication flows for clients.

A. Security Key Authentication (Recommended for Agents/Robotics)

For automated services, use a Security Key which can be generated in the OmniEdge Dashboard.

Endpoint: POST /api/v2/auth/login/security-key

Request Body:

{
  "key": "your_security_key"
}

Response:

{
  "token": "JWT_ACCESS_TOKEN",
  "refresh_token": "JWT_REFRESH_TOKEN"
}

Usage: Include Authorization: Bearer <token> in the header of all subsequent requests.

B. Session OAuth Flow (Recommended for Desktop/Mobile)

For user-facing applications, use the session flow to authenticate via a browser.

1. Initialize Session: GET /api/v2/auth/login/session
   • Returns a uuid and an auth_url.
2. Authorize: Open the auth_url in the system browser for the user to login.
3. Listen: Connect to the WebSocket: wss://api.omniedge.io/login/session/{uuid} to receive the tokens once authentication is complete.

2. Device Lifecycle

Every client must register as a unique device to the backend.

Register Device

Each client should generate and persist a unique hardware_id.

Endpoint: POST /api/v2/devices

Request Body:

{
  "name": "My-Robot-Agent",
  "hardware_uuid": "unique-persistent-uuid",
  "platform": "linux"
}

Heartbeat

To stay "online" in the dashboard and receive updates, clients MUST send a heartbeat every 30-60 seconds.

Endpoint: POST /api/v2/devices/heartbeat

Request Body:

{
  "hardware_id": "unique-persistent-uuid",
  "is_exit_node": false
}

Response:

{
  "message": "Heartbeat received",
  "last_seen": "2024-03-20T10:00:00Z",
  "exit_nodes": {
    "vn_id_1": "100.66.0.5"
  }
}

Note: exit_nodes contains a mapping of Virtual Network IDs to the Virtual IP of the exit node selected for this device.

3. Virtual Networking

Once a device is registered, it can join or leave virtual networks.

Join a Virtual Network

Joining a network assigns a Virtual IP and provides the necessary mesh credentials.

Endpoint: POST /api/v2/virtual-networks/{network_id}/devices/{device_id}

Response:

{
  "cluster": "cluster name",
  "secret_key": "mesh_encryption_key",
  "virtual_ip": "100.66.0.5",
  "virtual_ip_v6": "fd10:66:0:0::5",
  "subnet_mask": "255.255.255.0",
  "subnet_prefix_v6": 120,
  "server": {
    "host": "nucleus.omniedge.io:51820",
    "name": "US East Server"
  }
}

Leave a Virtual Network

Endpoint: DELETE /api/v2/virtual-networks/{network_id}/devices/{device_id}

4. Exit Node Logic

Acting as an Exit Node

1. Local Consent: The client must set is_exit_node: true in its heartbeat.
2. Network Permission: A network admin must enable the exit node status for the device in that specific network via: PUT /api/v2/virtual-networks/{vn_id}/devices/{dev_id} with {"is_exit_node": true}.

Using an Exit Node

If a user selects an exit node for your client, the heartbeat response will include the exit node's virtual IP in the exit_nodes object. Your client should then:

1. Monitor the heartbeat response for changes.
2. If an exit node is present, route all internet traffic (0.0.0.0/0 and ::/0) through the OmniEdge tunnel.

5. IPv6 Dual-Stack

OmniEdge assigns both IPv4 and IPv6 ULA addresses.

• IPv4 Range: Standard private ranges (e.g., 100.66.0.0/10).
• IPv6 Range: ULA prefix fd00::/8.

Clients should configure the TUN interface with both addresses and routes to ensure seamless dual-stack connectivity.

6. Custom User Servers

Users can host their own Nucleus (signaling) and Relay servers.

List Custom Servers

Endpoint: GET /api/v2/user-servers

Create Custom Server

Endpoint: POST /api/v2/user-servers

Request Body:

{
  "name": "My Home Lab",
  "host": "nucleus.example.com:51820",
  "country": "US"
}

Update Custom Server

Used when running OmniEdge in Nucleus Mode or Dual Mode to update the server's public endpoint or metadata.

Endpoint: PUT /api/v2/user-servers/{id}

Request Body:

{
  "name": "Updated Name",
  "host": "new-nucleus.example.com:51820",
  "country": "US"
}

Delete Custom Server

Endpoint: DELETE /api/v2/user-servers/{id}

7. Error Handling

• 401 Unauthorized: Token expired. Attempt to use refresh_token at POST /api/v2/auth/refresh or re-authenticate.
• 403 Forbidden: Access denied to the specific network or device.
• 429 Too Many Requests: Rate limit reached.
• 400 Bad Request: Validation error or limit reached (e.g., maximum devices for the user's plan).