Authentication - NetlyDB documentation

Embedded use

An embedded application calls NetlyDB in-process, so there is nothing to authenticate: access control is your application's. Authentication applies to the hosted modules, which open ports.

Which credential protects which surface. In-process calls need none; the hosted modules require one by default and bind to localhost; cluster peers share a secret.

REST API and MCP server

Both require authentication by default (Security.RequireApiAuthentication), and a host that enables one without any credentials configured fails at startup instead of running open. Anonymous access from the local machine is opt-in (AllowLoopbackAnonymous). The /health probes are anonymous by design.

Method	How	Edition
API keys	Clients send `X-NetlyDB-ApiKey`. Configure plaintext keys (`ApiKeys`) or, preferably, SHA-256 hashes (`ApiKeyHashes`). Several entries allow rotation.	Community
JWT bearer / OIDC	`EnableJwtBearer` with `JwtAuthority`, `JwtAudience` and optionally `JwtIssuer`.	Enterprise

builder.Services.AddNetlyDB(options =>
{
    // API keys (Community). Prefer hashes: the plaintext key then never sits in configuration.
    // Several entries allow rotation. Clients send the key in the X-NetlyDB-ApiKey header.
    options.Security.ApiKeyHashes = [currentKeyHash, previousKeyHash];

    // JWT bearer / OIDC (Enterprise).
    options.Security.EnableJwtBearer = true;
    options.Security.JwtAuthority = "https://login.example.com/tenant";
    options.Security.JwtAudience = "netlydb-api";

    // HTTPS for the REST API and MCP server.
    options.Security.EnableTls = true;
    options.Security.CertificatePath = "/etc/netlydb/api.pfx";
});

Management UI

The Management UI uses its own sign-in with user accounts managed on its Settings page. On first start it creates an admin account and writes the generated password to the log once. See Management UI.

Cluster nodes

Nodes authenticate each other with a pre-shared cluster secret, and should use TLS on any network they do not fully trust. See Clustering & replication.

TLS

HTTPS for the REST API and MCP server is off by default; enable Security.EnableTls with a PFX certificate at Security.CertificatePath. All three hosted modules bind to localhost; exposing them further is done through a reverse proxy, which is also where you would terminate TLS for the Management UI.