API

Two protocol surfaces

EON Path has two distinct APIs, and it’s easy to conflate them:

1. VPN authentication protocol — a raw TCP handshake that authenticates a client to the server and establishes a VPN session, using ML-DSA-87 challenge-response authentication and an ML-KEM-1024 key exchange. This is not an HTTP API.
2. Management API — a REST/JSON API, served by eonpath-api, for registering accounts, publishing and querying ML-DSA public keys, and managing VPN IP leases. It has its own authentication (username/password login returning a bearer token) that is unrelated to the VPN handshake.

The two touch at exactly one point: during the VPN handshake, the server calls the management API to confirm a connecting client’s public key is registered and active (see step 4 below).

VPN authentication protocol (ML-DSA-87 challenge-response)

• Transport: plain TCP to the WireGuard routing method’s key-exchange listener — EONPATH_WG_KEX_ADDR on the server, default 0.0.0.0:9998 (see Configuration: Server).
• Framing: a custom, length-prefixed binary protocol (4-byte big-endian length, then the payload) — not HTTP, so there are no JSON request/response bodies for this part of the API.
• Why ML-DSA-87 and ML-KEM-1024: see Post-Quantum Cryptography.

Challenge request

The first phase authenticates the client’s identity key to the server:

Session establishment

Once the client is authenticated, the server proves its own identity and both sides derive the key material for the WireGuard tunnel:

Management API

Base URL

http://localhost:8080/api

The default address matches EONPATH_API_ENDPOINT in the server’s environment file — see Configuration: Server.

Authentication

Most endpoints require a bearer token, obtained from /api/auth/login:

Authorization: Bearer <token>

This token authenticates account operations (managing your profile, uploading keys, requesting IP leases) — it is not used anywhere in the VPN authentication protocol described above, which authenticates the VPN connection itself using ML-DSA-87 signatures instead of passwords or tokens.

Endpoints

Endpoint registration

POST /endpoints replaced an older POST /endpoints/:name, which was trust-on-first-use — whatever X-API-Key the first caller sent became the key for that name. Registration is now a signed payload: the server’s ML-DSA-87 identity signs it, the first push also presents the licence key, and after that the signature alone authenticates the server. The URL the server registers with is part of what it signs, so it must match one of the API’s EONPATH_API_AUDIENCES entries. Replays are bounded by a nonce cache.

An endpoint carries a state — standby or active — set on the server, not in the API (see Configuration: Server). GET /endpoints returns only the active ones. Unlicensed endpoints in a push are skipped; the rest of the push is accepted rather than the whole thing being refused.

Administrative and billing routes

Two route groups exist for EON Core, not for tenants, and each is registered only when its token is configured — without the token the routes don’t exist rather than refusing. Both take the token in the X-Admin-Token header.

The billing group accepts a second, read-only token (EONPATH_BILLING_TOKEN) so an invoicing job never holds a token that can issue or revoke a licence. Neither token replaces restricting /api/admin at the reverse proxy — a shared secret on a published path is one leak away from a self-issued licence.

Register

POST /api/auth/register

Request:

{
  "username": "alice",
  "email": "alice@example.com",
  "password": "a-strong-password"
}

Response (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "alice",
  "email": "alice@example.com",
  "created_at": "2026-01-15T10:30:00Z"
}

Login

POST /api/auth/login

Request:

{
  "username": "alice",
  "password": "a-strong-password"
}

Response (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-01-16T10:30:00Z",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "alice"
  }
}

Errors

Error responses share a common shape:

{
  "error": "error message here"
}

Authentication endpoints are rate-limited to 5 requests/minute; other endpoints to 30 requests/minute.