Skip to content

API

The API is a FastAPI application, versioned under /api/v1. Every data route requires authentication; /healthz and GET /api/v1/setup are public by design.

Authentication

  • HTTP Basic: GSLB_API_USER / GSLB_API_PASSWORD.
  • Static Bearer: GSLB_API_TOKEN (also used by the DNS nodes).
  • Read-only token: GSLB_API_RO_TOKEN authenticates every read and is refused on every write (403 read-only credential). When it is the only credential configured, reads work, the token holder's writes answer 403 read-only credential and an anonymous write answers 403 writes are disabled.
  • OIDC session cookie (optional, since 0.11.3): gslb_session, signed, set by /auth/callback. It carries a role — reader, operator or admin — and a write made with it must also carry X-Requested-With: gslb-console and a matching Origin. Without GSLB_OIDC_ISSUER nothing changes. See OIDC.
  • Roles: reader reads and computes; operator also tests a probe and checks the VIP; admin writes. Basic and the tokens are admin, the read-only token is reader.
  • Fail closed: with nothing configured, every data route answers 503.
  • A credential over plain HTTP is refused (403, actionable message). The precedence is: GSLB_REQUIRE_TLS=1 refuses and wins over everything; GSLB_REQUIRE_TLS=0 allows (deprecated alias); GSLB_ALLOW_PLAINTEXT_AUTH=1 allows (lab switch); otherwise refuse. /healthz is never affected.
  • GSLB_TRUST_PROXY=1 is the only way the transport (X-Forwarded-Proto) and the source address (X-Real-IP, else the last X-Forwarded-For hop) are read from headers; without it only the connection itself counts. The hop into the console's nginx must be HTTPS for that header to say https.

The lot 2 prefix /api remains an alias, hidden from the OpenAPI schema. It is removed only when /api/v2 lands, never before. /auth/* has no alias: a callback URL is registered once at the provider, and a second spelling of it is a second way to be wrong.

Routes

Every route below is relative to /api/v1, except /healthz, which stays at the root. Methods in parentheses are the second verb on the same path.

Route Method Purpose
/healthz GET Liveness, unauthenticated
/auth/methods GET What the sign-in page may offer: oidc, basic, token, display_name, preset, logout_url (public)
/auth/login GET Start the OIDC flow; ?next=/... is a local path only
/auth/callback GET Finish it: state, code exchange, ID token, session cookie
/auth/logout POST Erase the session cookie (CSRF header required)
/auth/me GET authenticated, actor, role, auth, can_read/operate/write/admin; 401 when anonymous
/settings/identity GET, PUT, DELETE Identity provider: effective settings, where each value comes from, callback URL, secret flags, recent changes. PUT stores console overrides (admin), DELETE erases them (admin)
/settings/identity/test POST Reach the effective or drafted provider once: {ok, checks: [{name, ok, detail}]}. Stores nothing, opens no session
/setup GET, PUT First start: needed?, then write the first configuration
/about GET Version, database schema, environment, server time zone, start time, auth, role
/config GET, PUT Structured form, canonical YAML, hash, last reload, drift; PUT validates, writes, acknowledges and rolls back on refusal
/config/raw GET Exact YAML and hash, for DNS nodes
/config/validate POST Dry run, diff, no write
/config/versions GET Configuration history
/config/versions.csv GET History export
/config/versions/{id} GET One version
/config/versions/{id}/diff GET Diff against the current file or another version
/config/versions/{id}/restore POST Restore through the normal save path
/stats GET Snapshot, counters, pools, drift, not-routed split
/stats/history GET Answers/fallbacks/failures per bucket
/stats/clients GET Query counts per client /24
/health GET Snapshot age and health transitions
/health/availability GET Availability strip per backend
/health/availability.csv GET Availability export for the selected window
/events GET Paginated routing journal: events and the filtered total
/events/filters GET The values the journal accepts: pool labels and reasons
/events.csv GET Journal export with the same filters, 10 000 rows at most
/suggestions GET Unregistered subnets, imbalance, flapping
/instances GET Fleet view: one row per node (addresses, port, version, workers, configuration state), the two disagreement lists, and the declared vip/vip_port
/instances/vip-check POST Query the VIP for heartbeat.<zone>; names the node that answered
/instances/{id}/snapshot POST DNS node pushes its snapshot
/instances/{id}/events POST DNS node pushes a batch of events
/instances/{id}/reload POST DNS node acknowledges a configuration
/metrics GET Prometheus exposition, text format 0.0.4 (also at the root, /metrics)
/probes/validate POST Validate a probe block without saving it
/probes/test POST Run one probe once (5 s at most), return the verdict and its reason
/templates GET, POST Probe template library
/templates/export GET Templates as JSON, never the links
/templates/import POST Import a JSON export
/templates/relink POST Follow a rename performed in the editor
/templates/{id} GET, PUT, DELETE One template; DELETE is refused (409) while a backend follows it
/templates/{id}/preview POST Impact of a draft: diff, backends rewritten, diverged, orphaned
/templates/{id}/apply POST Write the draft into the followers, then update the library
/templates/{id}/links POST, DELETE Attach or detach a backend

Windows are 1h, 24h or 7d.

The identity settings live under /api/v1 only, like /auth/*: they configure the callback those routes use, and a second spelling of that contract would be a second way to be wrong. Reading them is a reader action; writing, erasing and testing are admin actions — an operator is refused like a reader. Refusals are the usual ones: 401 anonymous, 403 when the role is too low (a read-only token gets 403 read-only credential), 400 with an actionable sentence when the payload would leave nobody able to sign in, and 503 on /auth/login when OIDC is enabled without GSLB_SESSION_SECRET. No secret is ever in a response: GSLB_OIDC_CLIENT_SECRET and GSLB_SESSION_SECRET are reported as secret_configured and session_secret_configured only, with the name of the variable to set. The redirect URI is computed (GSLB_PUBLIC_ORIGIN plus /api/v1/auth/callback, or GSLB_OIDC_REDIRECT_URI) and never editable.

/stats also returns not_routed and not_routed_reasons: the queries that reached no backend (REFUSED, NXDOMAIN, an empty answer, SERVFAIL, a liveness check). They stay in by_pool as none for the contract; the console draws the pools alone and states this volume underneath, because one health check every two seconds would otherwise dwarf a small site's traffic.

/instances is empty in the single-host file mode: there is no fleet to show. In HA mode a node is a host (GSLB_INSTANCE) and each row carries the processes it runs, so one machine with eight workers stays one row.

Examples

# Basic
curl -u admin:secret http://gslb:8080/api/v1/stats

# Bearer
curl -H "Authorization: Bearer $GSLB_API_TOKEN" \
     http://gslb:8080/api/v1/instances

# Validate a form without writing it
curl -u admin:secret -X POST http://gslb:8080/api/v1/config/validate \
     -H 'Content-Type: application/json' -d @form.json

# Which node holds the VIP, and what it runs
curl -u admin:secret -X POST http://gslb:8080/api/v1/instances/vip-check \
     -H 'Content-Type: application/json' -d '{}'

# The scrape, with the read-only token: the same series at /metrics
curl -H "Authorization: Bearer $GSLB_API_RO_TOKEN" \
     http://gslb:8080/api/v1/metrics

curl -u admin:secret http://gslb:8080/api/v1/config returns {"form": ..., "yaml": ..., "sha256": ..., "reload": ..., "drift": ...}.

Configuration history

/config/versions returns one entry per save, restore, setup or template application:

{"id": 42, "ts": 1763556000.0, "sha256": "…", "trigger": "api",
 "actor": "admin", "source_ip": "203.0.113.9", "applied": true, "error": null}

source_ip is the administrator's address, recorded since 0.11 (schema 7); it is NULL for older rows and whenever nothing trustworthy could be read. With GSLB_TRUST_PROXY=1 it comes from X-Real-IP, else from the last hop of X-Forwarded-For, validated as an address; otherwise it is the socket peer. The CSV export carries the same column between actor and applied. See Who changed the DNS.

Errors

Code Meaning
400 Invalid configuration or probe (validation message in the detail)
401 Missing or wrong credentials; an ID token that is not ours; the provider refused the code
403 Read-only credential on a write, a role too low for the route, writes disabled, a bad CSRF header or origin, no mapped OIDC group, or a credential over plain HTTP (TLS required by default since 0.11)
404 Unknown version, template, instance, or a link whose backend is gone
409 Setup already done, or a template still followed
500 The configuration file cannot be read
503 No credential configured, the API is closed; OIDC half-configured or GSLB_SESSION_SECRET missing
502 The identity provider is unreachable, or its documents are inconsistent

A save that the DNS refuses returns 200 with applied: false, the error and the per-instance acknowledgements; the file is rolled back.

OpenAPI

FastAPI serves the schema at /openapi.json and Swagger UI at /docs on the API port. In the HA compose the API publishes no port: read it from the management host (127.0.0.1:8000) or add a proxy location if you need it remotely. The bodies are not described by response models yet: the console carries the shapes by hand in web/src/api/types.ts.