Skip to main content

Users & Access Keys API

Lioran S3 includes native user identity and credential management APIs accessible via client.users and client.accessKeys.

1. User Management (client.users)​

:::info Administrative Privileges Creating, updating, disabling, deleting users, or resetting passwords requires an authenticated account with the admin role. :::

Create a User Account​

import { BastionClient, type UserRole } from "@liorans3/driver";

const client = new BastionClient("bastion://admin:YOUR_PASSWORD@127.0.0.1:27118");

const newUser = await client.users.create({
  username: "ci-bot",
  password: "StrongPasswordHere123!",
  role: "readwrite", // "admin" | "readwrite" | "readonly"
});

console.log(`Created user ${newUser.username} with role ${newUser.role}`);

List All Users​

const users = await client.users.list();

for (const u of users) {
  console.log(`User: ${u.username} | Role: ${u.role} | Active: ${u.is_active} | Must Change Pass: ${u.must_change_password}`);
}

Update User Role & Status​

// Promote user to admin
await client.users.update("developer", {
  role: "admin",
  isActive: true,
});

// Or use helper methods:
await client.users.disable("temp-contractor");
await client.users.enable("temp-contractor");

Self-Service Password Change​

Any authenticated user can change their own password without administrator intervention:

const message = await client.users.changePassword(
  "CurrentPassword123!",
  "NewSecurePassword456!"
);
console.log("Result:", message);

Administrative Password Reset​

Administrators can reset any user's password and optionally require them to change it on their next login:

await client.users.resetPassword("developer", "TemporaryPassword789!", {
  mustChangePassword: true,
});

Delete a User Account​

const deleted = await client.users.delete("obsolete-user");
console.log("Deleted:", deleted);

2. Programmatic Access Keys (client.accessKeys)​

Programmatic Access Keys are ideal for backend services, daemon processes, and CI/CD pipelines.

Create an Access Key​

const key = await client.accessKeys.create({
  name: "production-backup-service",
  expiresAt: new Date(Date.now() + 90 * 86400 * 1000), // 90-day expiration
});

console.log("Key ID:", key.id);         // e.g. "bk_live_0192a7b8c9d0"
console.log("Secret Key:", key.secret); // e.g. "sk_live_9f83a21b4c7e..."
console.log("Owner:", key.owner);

:::warning Secret Displayed Once The secret field is returned only once during initial creation or rotation. It cannot be retrieved later. :::

List Access Keys​

// List current user's keys
const myKeys = await client.accessKeys.list();

// Admin: Filter keys by specific owner
const userKeys = await client.accessKeys.list({ user: "ci-bot" });

for (const k of userKeys) {
  console.log(`Key ID: ${k.id} (${k.name}) - Revoked: ${k.is_revoked}`);
}

Rotate an Access Key​

Rotating a key immediately revokes the old secret and generates a new secret for the same Key ID:

const rotated = await client.accessKeys.rotate("bk_live_0192a7b8c9d0");

console.log("Key ID:", rotated.id);
console.log("New Secret Key:", rotated.secret);

Revoke / Delete an Access Key​

const deleted = await client.accessKeys.delete("bk_live_0192a7b8c9d0");
console.log("Access key revoked:", deleted);