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.

Endpoint Visibility

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

[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

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:

[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:

bext config endpoints list

Output:

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:

bext config endpoints list --json

Show Visibility Status

Compact view of which groups are on or off:

bext config endpoints show

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:

bext config endpoints disable metrics

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:

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

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

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:

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

JSON output:

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

Hash a Password

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

bext config credentials hash

Or non-interactively:

bext config credentials hash "my-password"

Prints only the argon2id hash:

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

Roles

Full Example

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

[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