API Reference

This page provides a complete reference for the Portal relay server HTTP API. Control-plane endpoints are served over the relay API HTTPS listener; tenant TLS is handled separately by the SDK using the relay’s keyless signing endpoint.

Response Envelope

Every API response uses a consistent JSON envelope:

{
  "ok": true,
  "data": { ... },
  "error": null
}

Error responses include a structured error object:

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "unauthorized"
  }
}

Authentication

Portal uses two separate authentication mechanisms depending on the caller.

SDK Authentication (SIWE Challenge/Response)

SDK clients authenticate using Sign-In with Ethereum (SIWE):

1. POST a challenge request to /sdk/register/challenge with your identity
2. Sign the returned SIWE message with your Ethereum private key
3. POST the signed message to /sdk/register to receive a JWT access token
4. Include the access token in subsequent requests via the X-Portal-Access-Token header or in the JSON request body

Admin Authentication (Wallet Session)

Admin clients authenticate with a wallet signature:

1. POST to /admin/auth/challenge with { "address": "<wallet-address>" }
2. Sign the returned SIWE message with the wallet
3. POST the signed message to /admin/auth/login
4. The server sets a portal_admin session cookie (HttpOnly, Secure, SameSite=Strict)
5. Include the cookie in subsequent admin requests
6. Sessions expire after 24 hours

The local agent has its own loopback wallet auth endpoints under /v1/agent/auth/*. Agent wallet sessions can read /v1/agent/status; mutating agent actions require the bearer token stored in the agent state directory. See Portal Agent for the local control API.

Endpoint Summary

SDK Endpoints

Admin Endpoints

System Endpoints

System Endpoints

These endpoints are small enough to document inline.

GET /healthz

Returns relay health status.

Response:

{
  "ok": true,
  "data": {
    "status": "ok"
  }
}

GET /discovery

Returns signed relay discovery descriptors for this relay and any known peer relays. Only available when discovery is enabled in the server configuration.

Response fields:

RelayDescriptor contains the signed relay contract and relay-reported telemetry:

Relay telemetry is sampled when the descriptor is issued; use issued_at to judge freshness.

Overlay peer support is advertised by supports_overlay. When it is true, wireguard_public_key and wireguard_port are present. The WireGuard endpoint host is the api_https_addr host, and the overlay IPv4 is derived from the WireGuard public key. Relay-local observations such as recent overlay reachability are not part of the signed descriptor.

Example:

curl https://relay.example.com/discovery

POST /discovery/announce

Submits this relay’s signed descriptor to a bootstrap relay so registry-external relays can enter the discovery mesh. Relays self-announce periodically when discovery is enabled.

Auth: Signed relay descriptor

Request fields:

Response fields:

POST /v1/sign

Keyless TLS signing endpoint. Used by the SDK-side tenant TLS server during the default stream handshake. Requests must include a valid lease access token in the X-Portal-Access-Token header.

Only available when the API server is configured with a TLS private key.

Returns 404 Not Found if signing is not configured.

GET /thumbnail/{hostname}

Returns a cached thumbnail screenshot for a registered tunnel hostname.

Response headers:

Returns 404 Not Found if the hostname is not registered or no thumbnail is available.

Example:

curl https://relay.example.com/thumbnail/myapp.relay.example.com

Error Codes

All error codes that may appear in the error.code field: