Endpoints & Credentials

bext exposes several groups of built-in endpoints for health checks, metrics, management, observability, and the admin panel. You can control which groups are visible and create admin credentials directly from the CLI.

Warning

When a group is disabled, its routes return 404 — not 403. External scanners will see no signal that the endpoint exists. Disabling metrics and admin is recommended for Internet-facing deployments.

Endpoint Visibility#

By default, all endpoint groups are enabled. Add an [endpoints] section to bext.config.toml to selectively hide groups:

toml

[endpoints]
health = true       # GET /health
metrics = false     # GET /metrics (Prometheus)
api = true          # /api/* management endpoints (requires super_admin)
obs = true          # /__bext/obs/* observability (requires viewer)
admin = true        # /__bext/admin/* panel

When a group is disabled, its routes are not registered at all -- requests return 404 as if the endpoints never existed. This is useful for hardening production deployments where you don't want to expose metrics or the admin panel externally.

Endpoint Groups#

Group	Endpoints	Auth Required	Description
`health`	`GET /health`	No	Health check for load balancers and uptime monitors
`metrics`	`GET /metrics`	No	Prometheus-format metrics export
`api`	`/api/*` (12 endpoints)	super_admin	Management API: invalidate, reload, deploy, config
`obs`	`/__bext/obs/*` (9 endpoints)	viewer	Dashboard, logs, cache inspect, alerts, SLOs, analytics
`admin`	`/__bext/admin/*` (40+ endpoints)	viewer	Full admin panel with login, cache, WAF, workers, flows

Admin Override#

The admin field in [endpoints] accepts true or false. When omitted, it follows the [admin].enabled setting. When explicitly set, it overrides it:

toml

[admin]
enabled = true        # Admin panel is configured...

[endpoints]
admin = false         # ...but hidden from the network

This lets you keep the admin config (users, JWT secret) in place while temporarily hiding the panel.

CLI: Manage Endpoints#

List All URLs#

Show every built-in endpoint URL, grouped by category, with current visibility status:

bash

bext config endpoints list

Output:

code

health  [enabled]
  GET  /health

metrics  [disabled]
  GET  /metrics (hidden)

api  [enabled]
  POST /api/invalidate
  POST /api/revalidate
  ...

obs  [enabled]
  GET  /__bext/obs/dashboard
  ...

admin  [enabled]
  GET  /__bext/admin/login
  ...

Use --json for machine-readable output:

bash

bext config endpoints list --json

Show Visibility Status#

Compact view of which groups are on or off:

bash

bext config endpoints show

code

Endpoint visibility:
  health   ●  GET /health
  metrics  ○  GET /metrics
  api      ●  /api/* management (super_admin)
  obs      ●  /__bext/obs/* observability (viewer)
  admin    ●  /__bext/admin/* panel (follows [admin].enabled)

Enable / Disable a Group#

Print the TOML snippet to add to your config:

bash

bext config endpoints disable metrics

code

To disable the metrics endpoints, add this to your bext.config.toml:

[endpoints]
metrics = false

Then restart bext for the change to take effect.

Valid group names: health, metrics, api, obs, admin.

CLI: Manage Credentials#

Create Admin Credentials#

Generate an [[admin.users]] entry with an argon2id-hashed password:

bash

bext config credentials create --username admin --role super_admin

When --password is omitted, bext prompts interactively with hidden input and confirmation:

code

Password:
Confirm:

Add this to your bext.config.toml:

[[admin.users]]
username = "admin"
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$..."
role = "super_admin"

Make sure [admin] enabled = true and jwt_secret is set.

For scripting and CI, pass the password directly:

bash

bext config credentials create \
  --username deploy-bot \
  --role viewer \
  --password "$ADMIN_PASSWORD" \
  --json

JSON output:

json

{
  "username": "deploy-bot",
  "password_hash": "$argon2id$v=19$m=19456,t=2,p=1$...",
  "role": "viewer"
}

Flag	Default	Description
`--username`	(required)	Username for the admin user
`--role`	`super_admin`	Role: `super_admin`, `tenant_admin`, or `viewer`
`--password`	(interactive)	Password (hidden prompt if omitted)
`--tenant-id`	(none)	Tenant ID (required for `tenant_admin` role)
`--json`	false	Output as JSON instead of TOML

Hash a Password#

If you just need the hash string for manual config editing:

bash

bext config credentials hash

Or non-interactively:

bash

bext config credentials hash "my-password"

Prints only the argon2id hash:

code

$argon2id$v=19$m=19456,t=2,p=1$randomsalt$hashvalue

Roles#

Role	Access Level	Description
`super_admin`	Full	All management and admin operations
`tenant_admin`	Scoped	Mutations within own tenant only
`viewer`	Read-only	Dashboard, logs, metrics, cache inspection

Full Example#

Tip

Use bext config credentials create rather than manually hashing passwords — it uses argon2id with tuned parameters and outputs the exact TOML snippet to paste into your config.

A production config with metrics hidden, admin enabled, and two users:

toml

[server]
listen = "0.0.0.0:443"

[admin]
enabled = true
jwt_secret = "change-me-to-a-random-secret"

[[admin.users]]
username = "admin"
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$..."
role = "super_admin"

[[admin.users]]
username = "ops"
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$..."
role = "viewer"

[endpoints]
health = true
metrics = false
api = true
obs = true

bext.config.toml — full [admin] and [endpoints] section reference
CLI Reference — bext config endpoints and bext config credentials commands
Operations: Security — hardening production deployments
Operations: Monitoring — using the obs and metrics endpoints
Operations: Logging — accessing logs via the admin panel

Endpoints & Credentials

Endpoint Visibility#

Endpoint Groups#

Admin Override#

CLI: Manage Endpoints#

List All URLs#

Show Visibility Status#

Enable / Disable a Group#

CLI: Manage Credentials#

Create Admin Credentials#

Hash a Password#

Roles#

Full Example#

Related#