Skip to main content

Auth and Admin Services

Learn how to use Auth and Admin Services in LioranDB to manage users, roles, sessions, and administrative operations. Understand how to handle authentication, permissions, password management, and database-level admin tasks securely.

Service handles on LioranDBClient​

The client exposes:

  • client.auth
  • client.users
  • client.roles
  • client.cluster
  • client.backups
  • client.settings

These are source-backed wrappers over the server HTTP API.

AuthService​

Public methods:

  • login(username, password)
  • refresh(refreshToken)
  • logout()
  • logoutAll()
  • me()
  • listSessions()
  • revokeSession(sessionId)
  • changePassword(newPassword, clearMustChange?)

login(username, password)​

Authenticates with explicit credentials and stores tokens inside the client.

const login = await client.auth.login("admin", "your-password");

console.log(login.principal.username);
console.log(login.session.session_id);
console.log(login.accessToken.length > 0);
console.log(login.refreshToken.length > 0);

refresh(refreshToken)​

Exchanges a refresh token for a fresh token pair.

const refreshed = await client.auth.refresh(previousRefreshToken);
console.log(refreshed.accessToken, refreshed.refreshToken);

logout()​

Revokes the current session.

The docs test exercises this through both:

  • client.auth.logout()
  • client.logout()

logoutAll()​

Revokes all sessions for the current user.

The docs test also exercises the convenience alias:

  • client.logoutAll()

me()​

Returns the current authenticated principal.

listSessions()​

Returns the current user's active sessions.

revokeSession(sessionId)​

Revokes one session by id.

The docs test creates an extra session specifically to verify this behavior.

changePassword(newPassword, clearMustChange?)​

Changes the current user's password.

UsersService​

Public methods:

  • list()
  • create(input)
  • get(userId)
  • update(userId, input)
  • delete(userId)
  • resetPassword(userId, input)
  • revokeSessions(userId)

CreateUserInput​

The real exported type is:

interface CreateUserInput {
  readonly username: string;
  readonly password: string;
  readonly roles?: readonly string[];
  readonly must_change_password?: boolean;
}

create(input)​

Creates a user record.

const user = await client.users.create({
  username: "ops-user",
  password: "SuperStrongPassword123!",
  roles: ["read_only"],
  must_change_password: false,
});

list()​

Returns a readonly array of UserRecord.

get(userId)​

Fetches one user by id.

update(userId, input)​

The real exported update type is:

interface UpdateUserInput {
  readonly enabled?: boolean;
  readonly roles?: readonly string[];
  readonly metadata?: Readonly<Record<string, string>>;
}

Example:

await client.users.update(user.id, {
  enabled: true,
  metadata: {suite: "docs-test"},
});

resetPassword(userId, input)​

The real exported type is:

interface ResetUserPasswordInput {
  readonly new_password: string;
  readonly clear_must_change?: boolean;
}

revokeSessions(userId)​

Revokes all sessions for the target user.

delete(userId)​

Deletes the user.

RolesService​

Public methods:

  • listPermissions()
  • listRoles()
  • createRole(input)
  • getRole(roleId)
  • updateRole(roleId, input)
  • deleteRole(roleId)

Permission names​

The real exported PermissionName union includes:

  • DatabaseList
  • DatabaseCreate
  • DatabaseDrop
  • CollectionList
  • CollectionCreate
  • CollectionDrop
  • DocumentRead
  • DocumentInsert
  • DocumentUpdate
  • DocumentDelete
  • IndexList
  • IndexCreate
  • IndexDrop
  • QueryExecute
  • QueryExplain
  • TransactionExecute
  • BackupList
  • BackupCreate
  • BackupDelete
  • BackupRestore
  • UserList
  • UserCreate
  • UserUpdate
  • UserDelete
  • UserRotateCredentials
  • SettingsRead
  • SettingsWrite
  • ClusterRead
  • ClusterManage
  • MetricsRead
  • AuditRead
  • SessionList
  • SessionRevoke
  • SystemNamespaceAccess

Grant scopes​

The real exported RoleGrantScope type is:

type RoleGrantScope =
  | { readonly kind: "cluster" }
  | { readonly kind: "database"; readonly database: string }
  | {
      readonly kind: "collection";
      readonly database: string;
      readonly collection: string;
    };

CreateRoleInput​

interface CreateRoleInput {
  readonly name: string;
  readonly grants: readonly PermissionGrant[];
}

listPermissions()​

Returns the permission names the server currently advertises.

listRoles()​

Returns a readonly array of RoleRecord.

createRole(input)​

Example:

const role = await client.roles.createRole({
  name: "readers",
  grants: [
    {
      permission: "DocumentRead",
      scope: {kind: "database", database: "default"},
    },
  ],
});

getRole(roleId)​

Current tested practical behavior:

  • using the role name is the safest follow-up lookup

updateRole(roleId, input)​

The real update shape is:

interface UpdateRoleInput {
  readonly grants: readonly PermissionGrant[];
}

Current tested practical guidance:

  • reuse your own original driver-shaped grants when updating
  • do not assume every server role response can be round-tripped blindly back into updateRole()

deleteRole(roleId)​

Current tested practical behavior:

  • deleting by role name is the most reliable path

ClusterService​

Public methods:

  • summary()
  • nodes()
  • partitions()
  • health()
  • readiness()
  • checkpoint()
  • compact()

summary()​

Returns ClusterSummary:

interface ClusterSummary {
  readonly node_id: number;
  readonly state: string;
  readonly nodes: readonly NodeConfigView[];
  readonly partitions: number;
  readonly protocol_version: number;
}

nodes()​

Returns readonly NodeConfigView[].

partitions()​

Returns readonly partition placement rows.

health()​

Returns readonly PartitionHealthView[].

readiness()​

Returns current readiness plus transitions.

checkpoint()​

Triggers cluster checkpoint maintenance and returns an acknowledgment object.

Current practical interpretation:

  • this is an admin trigger
  • treat success as "request accepted"
  • do not assume it means every internal durability task has fully drained before the response is returned

compact()​

Triggers compaction maintenance and returns an acknowledgment object.

Current practical interpretation:

  • this is also an admin trigger
  • treat the response as acknowledgment rather than as a detailed compaction report

BackupsService​

Public methods:

  • list()
  • create(input?)
  • get(backupId)
  • delete(backupId)
  • verify(backupId)
  • restore(backupId, input)
  • getRestoreJob(jobId)

BackupCreateInput​

The real exported type is:

interface BackupCreateInput {
  readonly label?: string;
  readonly scope?: "cluster" | "local_node";
}

list()​

Returns readonly BackupJobRecord[].

create(input?)​

Creates a backup job and returns a BackupJobRecord.

Current docs-test-backed behavior:

  • create() returns a backup id immediately
  • production code should still poll get(backupId) until status becomes "completed" before assuming the archive exists
const backup = await client.backups.create({
  label: "docs-demo",
  scope: "local_node",
});

get(backupId)​

Returns the current BackupJobRecord.

The real record includes:

  • backup_id
  • label
  • backup_type
  • status
  • requested_by
  • created_at_ms
  • started_at_ms
  • completed_at_ms
  • failed_at_ms
  • error
  • archive_path
  • manifest_path
  • size_bytes
  • checksum_sha256
  • partition_snapshot_boundary
  • topology_toml
  • engine_version
  • database_metadata
  • cluster_complete
  • scope

verify(backupId)​

Verifies the created archive and returns the updated BackupJobRecord.

The docs test now waits for completion first and then calls verify().

delete(backupId)​

Deletes the archive and removes the stored backup job record.

The docs test now uses this to clean up backup files after exercising the API.

RestoreInput​

The real exported type is:

interface RestoreInput {
  readonly confirmation: string;
  readonly disable_safety_backup?: boolean;
}

restore(backupId, input)​

Schedules a restore and returns:

interface RestoreResponse {
  readonly job: RestoreJobRecord;
  readonly restart_required: boolean;
}

Current tested practical behavior:

  • restore is a scheduled maintenance operation
  • the server responds with restart_required: true
  • follow-up state can be checked with getRestoreJob(jobId)

Example:

const restore = await client.backups.restore(backup.backup_id, {
  confirmation: `RESTORE ${backup.backup_id}`,
  disable_safety_backup: true,
});

getRestoreJob(jobId)​

Returns the scheduled restore job record.

The real exported restore record includes:

  • job_id
  • backup_id
  • requested_by
  • confirmation
  • status
  • created_at_ms
  • started_at_ms
  • completed_at_ms
  • failure
  • staging_paths
  • safety_backup_id
  • validation_results
  • per_node_progress

SettingsService​

Public methods:

  • get()
  • update(values)
  • getCors()
  • updateCors(settings)
  • getPerformance()
  • updatePerformance(settings)
  • getLimits()
  • updateLimits(settings)
  • getBackups()
  • updateBackups(settings)

get()​

Returns the generic redacted settings map.

update(values)​

Patches the generic settings map.

getCors() and updateCors(settings)​

Read and replace CorsSettings.

getPerformance() and updatePerformance(settings)​

Read and replace PerformanceSettings.

Real exported performance fields include:

  • controller_interval_ms
  • query_parallelism_cap
  • result_batch_size
  • compaction_permits
  • checkpoint_permits
  • replication_batch_size
  • backup_compression_concurrency
  • index_warming_enabled
  • background_work_enabled
  • high_watermark_percent
  • critical_watermark_percent
  • emergency_reserve_percent

getLimits() and updateLimits(settings)​

Read and replace LimitSettings.

getBackups() and updateBackups(settings)​

Read and replace BackupSettings.

Real exported backup settings include:

  • compression_level
  • verify_after_create
  • require_cluster_complete
  • hourly
  • daily
  • weekly
  • monthly
  • retention

Practical pattern: admin smoke test flow​

The repository docs test currently exercises this rough flow:

  1. connect and authenticate
  2. create temp users and roles
  3. hit cluster summary, health, readiness, checkpoint, and compact
  4. read and round-trip settings
  5. create backup
  6. poll backup completion
  7. verify backup
  8. schedule restore
  9. inspect restore job
  10. delete backup artifacts during cleanup

That means the examples on this page are not just theoretical; they match the real end-to-end test coverage in the repository.