Skip to main content

Auth & users

LioranClient exposes authentication + user management methods.

Related page: Maintenance & core APIs for snapshots, server pause/resume/stop, and core introspection endpoints.

connect() (URI auto-detect)​

connect() chooses behavior based on your URI:

  1. lioran://username:password@host:port → logs in and stores a JWT token
  2. liorans://username:password@host:port → same as lioran://, but uses HTTPS
  3. liorandb://dbUsername:dbPassword@host[:port]/databaseName → uses connection-string mode (database-scoped identity)
  4. liorandbs://dbUsername:dbPassword@host[:port]/databaseName → same as liorandb://, but uses HTTPS
  5. http(s)://host:port → no auto-login (call login() / superAdminLogin() or setToken() / setConnectionString())

Example: lioran:// (username/password)​

import { LioranClient } from "@liorandb/driver";

const client = new LioranClient("lioran://admin:admin@localhost:4000");
await client.connect();

console.log(client.isAuthenticated(), client.getUser()?.role);

Example: liorandb:// (database-scoped connection string)​

This mode authenticates as a single database only (no user-management APIs). In practice, database-scoped identities are meant for application traffic, not for admin/user-management endpoints.

import { LioranClient } from "@liorandb/driver";

const client = new LioranClient(
  "liorandb://db_user:db_pass@localhost:4000/app"
);
await client.connect();

const db = await client.db("app");
console.log(await db.collection("items").count());

login(username, password)​

Use this with http:// or https:// URIs.

import { LioranClient } from "@liorandb/driver";

const client = new LioranClient("http://localhost:4000");
await client.login("admin", "admin");

console.log(client.getToken());

superAdminLogin(secret)​

Use the raw contents of the server secret.key.

import fs from "node:fs";
import { LioranClient } from "@liorandb/driver";

const secret = fs.readFileSync("./secret.key", "utf8").trim();
const client = new LioranClient("http://localhost:4000");
await client.superAdminLogin(secret);

console.log(client.getUser());

Session helpers​

setToken() / getToken()​

client.setToken("<jwt>");
console.log(client.getToken());

setConnectionString() / getConnectionString()​

client.setConnectionString("liorandb://db_user:db_pass@localhost:4000/app");
console.log(client.getConnectionString());

isAuthenticated() / getUser() / logout()​

console.log(client.isAuthenticated(), client.getUser());
client.logout();
console.log(client.isAuthenticated());

User APIs (require JWT auth)​

me()​

const me = await client.me();
console.log(me.user.username);

register(...)​

register() is a protected route (admins/super-admins).

await client.register({ userId: "editor", password: "secret123", role: "admin" });

listUsers()​

const users = await client.listUsers();
console.log(users.map((u) => ({ userId: u.userId, role: u.role })));

issueUserToken(userId)​

const out = await client.issueUserToken("editor");
console.log(out.token);

CORS helpers (require JWT auth)​

updateMyCors(origins)​

await client.updateMyCors(["https://app.example.com"]);

updateUserCors(userId, origins)​

await client.updateUserCors("editor", ["https://app.example.com"]);

Public info APIs​

health() / info()​

console.log(await client.health());
console.log(await client.info());

Embedded docs APIs​

listDocs() / getDoc(id)​

const list = await client.listDocs();
const first = list.docs[0];
if (first) console.log(await client.getDoc(first.id));

Maintenance APIs​

maintenanceStatus()​

const status = await client.maintenanceStatus();
console.log(status.snapshots);

listSnapshots() / createSnapshotNow()​

console.log(await client.listSnapshots());
console.log(await client.createSnapshotNow());

compactAllDatabases()​

console.log(await client.compactAllDatabases());

For server stop/pause/resume/restore and the core* introspection APIs, see Maintenance & core APIs.