Authentication and TLS

TCP authentication#

Server:

const db = new AxioDB({
  TCP: true,
  TCPAuth: true,
  RootName: 'MyDatabase',
  CustomPath: './data',
});

Client:

// Pass credentials in the constructor — connect() authenticates automatically
const client = new AxioDBCloud("axiodb://localhost:27019", {
  username: 'admin',
  password: 'admin',
});
await client.connect();
 
console.log(client.authenticatedUser);
// { username: 'admin', role: 'Super Admin', mustChangePassword: false }
 
// Or authenticate after connecting
const client2 = new AxioDBCloud("axiodb://localhost:27019");
await client2.connect();
await client2.login('admin', 'admin');

What's enforced#

Every command except PING/DISCONNECT/AUTHENTICATE requires a prior successful login on that connection.
Same role permissions as the GUI, checked per command — a View-role user gets 403 on CREATE_DB.
Shared per-IP login rate limiter with the GUI: 5 failed attempts in 15 minutes locks that IP out for 15 minutes (429).
Accounts still needing a forced password change are rejected outright (403) — complete it via the GUI first.
A password reset, role change, or deletion via the GUI immediately forces an already-open TCP connection to re-authenticate.

Known limitation: there's no TCP command yet to change a password — that has to go through the GUI.

TLS encryption#

By default the TCP protocol is plaintext — anyone capturing traffic between client and server can read your data and, if TCPAuth is on, your password. TLS is off by default; nothing here is required, and existing plaintext deployments keep working unless you turn it on.

You must provide your own certificate and key — AxioDB never generates one for you.

Get a cert and key

For local, dev, or private use, generate a self-signed one:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"

For a real production deployment, use a cert from a real CA (Let's Encrypt, your org's CA, your cloud provider's managed cert) instead — the rest of the setup is identical.

Point the server at them

const { AxioDB } = require('axiodb');
const db = new AxioDB({
  TCP: true,
  TLS: true,
  TLSCertPath: './cert.pem',
  TLSKeyPath: './key.pem',
});

If TLS: true but either path is missing or unreadable, AxioDB throws immediately at startup — it never silently falls back to plaintext.

Point the client at the same cert

Only needed because it's self-signed:

const { AxioDBCloud } = require('axiodb');
const client = new AxioDBCloud("axiodb://localhost:27019", {
  tls: true,
  tlsCAPath: './cert.pem',
});
await client.connect();

Without tlsCAPath, the client refuses to connect to a self-signed server by default (tlsRejectUnauthorized defaults to true). Only set tlsRejectUnauthorized: false for local or dev testing, never in production.

Running TLS in Docker#

Cert and key files need to get into the container. Your cert files live on your real machine; a Docker bind mount (-v) makes a folder from your machine visible inside the container, and you point the env vars at the in-container path, not your machine's real path.

# cert.pem and key.pem are really at /home/you/mycerts/ on your machine.
docker run -d --name axiodb-server \
  -p 27018:27018 -p 27019:27019 \
  -v /home/you/mycerts:/certs:ro \
  -e AXIODB_TLS=true \
  -e AXIODB_TLS_CERT_PATH=/certs/cert.pem \
  -e AXIODB_TLS_KEY_PATH=/certs/key.pem \
  theankansaha/axiodb

The rule: AXIODB_TLS_CERT_PATH must always match the right-hand side of the -v mount, never the real path on your machine.

Updated Aug 10, 2026