Skip to content

Authentication

HyperbyteDB can require credentials on data-plane HTTP methods while leaving health and monitoring endpoints open (by default). Passwords are verified with Argon2 and stored in metadata as PHC-format strings.

Config: set [auth] enabled = true or HYPERBYTEDB__AUTH__ENABLED=true. See the [auth] section in Configuration.

What requires a login (any valid user)

When authentication is enabled, these routes require a successful check using one of the methods below:

Route Notes
POST /write Line protocol, MessagePack, or columnar bodies
GET / POST /query InfluxQL

These layers run after optional rate limiting (if [rate_limit] is enabled): a client may get 429 before auth runs.

Public endpoints (no credentials)

The following are not wrapped in the user auth middleware when auth.enabled is true:

Route Purpose
GET / HEAD /ping Liveness / version headers
GET / HEAD /health JSON health
GET / HEAD /health/ready Readiness (chDB probe)
GET /metrics Prometheus text

GET / DELETE /api/v1/statements (statement summary) is also unauthenticated today. It only exposes recent query digests and timings when statement summary is enabled, but in locked-down environments you should still restrict access at the network (or proxy) layer.

Cluster / internal / Raft routes (admin only)

When cluster (or Raft) routes are present and auth.enabled is true, the stack uses a separate middleware: internal_auth_layer in auth_middleware.rs.

  • Valid credentials for a user with admin: true → request proceeds.
  • Valid non-admin user → 403 admin privileges required for internal routes.
  • Missing/invalid credentials → 401 authorization failed.
  • If auth.enabled is false → internal routes are not checked at the HTTP layer (rely on network policy / mTLS in production).

Uses the same credential delivery as Sending credentials (u/p, Authorization: Basic, or Authorization: Token).

Affects paths such as /internal/*, /cluster/* (including replication and Raft) when those routes are mounted; exact set depends on cluster/Raft being enabled. See Cluster, replication, and internal routes in the API reference.

Operational note: create at least one admin user (below) before turning on auth in a clustered deployment if operators or automation must call internal APIs.

Sending credentials (order of precedence)

The server examines sources in this order; the first successful extraction wins.

  1. Query parameters: u and p (e.g. ?u=admin&p=secretpassword on GET /query or POST /write).
  2. HTTP Basic: Authorization: Basic <base64("username:password")>.
  3. InfluxDB-style token header: Authorization: Token username:password (literal Token prefix, then user:pass with a single colon separator).

Implementation: extract_credentials in auth_middleware.rs (Custom Base64 decode for Basic, no extra crate).

Enabling auth in config

[auth]
enabled = true

Then create users with InfluxQL (via /query over HTTP, or a client that supports the same). First session may need a bootstrap path if you lock /query immediately—typical flow is: enable auth, create admin user in same deployment step, or use a side channel for the first CREATE USER.

User management (InfluxQL)

Run through /query (or POST with form q=...).

Action Example
Create user (non-admin) CREATE USER "reader" WITH PASSWORD 'secret'
Create admin CREATE USER "admin" WITH PASSWORD 'secret' WITH ALL PRIVILEGES (or include ADMIN in the statement—see parser)
List users SHOW USERS
Change password SET PASSWORD FOR "reader" = 'newsecret'
Remove user DROP USER "reader"

Admin flag: the parser sets admin if the CREATE USER text contains ALL PRIVILEGES or ADMIN (case-insensitive). Only admin users can access internal cluster routes when auth is on.

Authorization model: no per-database GRANT/REVOKE. GRANT / REVOKE are accepted as no-ops for compatibility. Plan around admin vs non-admin only.

Design reference

See also