Admin HTTP API

The /api/admin/* surface manages the gateway's backends (upstream model providers) and aliases (model-name → model-id redirection). It is the HTTP counterpart of the RPC management plane (see the JSON-RPC API) and is primarily used by operators and the admin UI.

Authentication

Every /api/admin/* route requires:

Authorization: Bearer $ARONA_ADMIN_TOKEN

ARONA_ADMIN_TOKEN is read from the environment at process start (GatewayServer::new). If the variable is unset, or the presented token does not match, the request is rejected with 401:

{
  "error": {
    "message": "Admin access required",
    "type": "auth_error",
    "code": "unauthorized"
  }
}

The bearer prefix is matched case-insensitively (Bearer or bearer).

Unlike the /v1/* surface, admin auth never falls back to API keys or JWTs, and it is enforced with an exact-token comparison — rotate the token by restarting the process with a new value.

Backends

Backends are the routable upstreams behind the gateway. Registration makes a backend routable immediately, persists its config for restart restore, probes it (flips healthy within ~1–2 s) and, for bridge URLs, keeps the tunnel alive. Backend types and URL semantics are detailed in Backends.

POST /api/admin/backends — register a backend

Request body (all fields optional except where noted):

Example:

curl -X POST http://192.0.2.10:8080/api/admin/backends \
  -H "Authorization: Bearer CHANGE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "external",
    "name": "mock-upstream",
    "url": "http://192.0.2.20:11434",
    "api_key": "sk-xxx",
    "models": ["Qwen/Qwen3-1.7B"]
  }'

Success → 200:

{ "status": "ok", "message": "backend registered" }

Registration side effects:

• The backend is registered and routable immediately (no restart needed).
• The config is persisted to the backend_configs table and restored at startup (a DB failure is logged but never blocks the response).
• A fire-and-forget probe runs right away so the backend flips healthy within ~1–2 s instead of staying fail-closed until the next 60 s health-checker round.
• For evernight:// URLs, a keepalive task watches the tunnel: on reconnect with a new local port it transparently rebuilds and re-registers the backend under the same name.

GET /api/admin/backends — list backends

{
  "backends": {
    "count": 2,
    "health": [
      ["backend_0:ExternalApi", "Healthy"],
      ["backend_1:Ollama", { "Unhealthy": "connection refused" }]
    ]
  },
  "models": [
    { "id": "Qwen/Qwen3-1.7B", "object": "model", "owned_by": "mock-upstream" }
  ]
}

• backends.count — number of healthy backends.
• backends.health — per-backend backend_<index>:<kind> label and health state (`Healthy` / `Degraded` / `Unhealthy`). The `<index>` is the router registration index used by `DELETE /api/admin/backends`.
• models — every model id routable today (same listing as `GET /v1/models`, without the quick-start merge; see [OpenAI-compatible REST](./openai-rest.md#get-v1models)).

DELETE /api/admin/backends — remove a backend

Identified by its router index in the JSON body — not by name:

curl -X DELETE http://192.0.2.10:8080/api/admin/backends \
  -H "Authorization: Bearer CHANGE_ME" \
  -H "Content-Type: application/json" \
  -d '{ "index": 0 }'

• Missing index → 400 {"error":{"message":"Missing 'index' field","type":"invalid_request","code":"missing_index"}}.
• Index out of range → 404 {"error":{"message":"Backend not found at given index","type":"invalid_request","code":"not_found"}}.
• Success → 200 { "status": "ok", "message": "backend removed" }.
• The persisted backend_configs row is deleted best-effort: the backend name is recovered from the `owned_by` of its model listing; a mismatch leaves the row in the store (DB failures are logged, never fatal).

Aliases

Aliases map one model name to another (alias → target) so requests for one model id route to a different backend model. Aliases are resolved before routing, so they apply uniformly to chat, embeddings and video lookups.

Aliases are in-memory router state only — they are not persisted and are lost on restart. Register them after startup or recreate them from your own provisioning state.

POST /api/admin/aliases — add an alias

curl -X POST http://192.0.2.10:8080/api/admin/aliases \
  -H "Authorization: Bearer CHANGE_ME" \
  -H "Content-Type: application/json" \
  -d '{ "alias": "my-model", "target": "Qwen/Qwen3-1.7B" }'

• Missing alias → 400 missing_alias; missing target → 400 `missing_target`.
• Success → 200 { "status": "ok", "message": "alias added" }.
• Adding an existing alias replaces its target.

GET /api/admin/aliases — list aliases

{
  "aliases": [
    { "alias": "my-model", "target": "Qwen/Qwen3-1.7B" }
  ]
}

Pairs are returned sorted by alias.

DELETE /api/admin/aliases — remove an alias

curl -X DELETE http://192.0.2.10:8080/api/admin/aliases \
  -H "Authorization: Bearer CHANGE_ME" \
  -H "Content-Type: application/json" \
  -d '{ "alias": "my-model" }'

• Missing alias → 400 missing_alias.
• Removing an unknown alias is a no-op success → 200 `{ "status": "ok", "message": "alias removed" }`.

Persistence summary