Managing users and reviewing the audit log in Sherpa

Sherpa’s user management and audit subsystem handles who can log in, what they can do, and a tamper-evident record of everything that happens. All user-management and audit-log operations are restricted to users with the admin role. If you are setting up Sherpa for the first time, this page explains how to bootstrap the first admin account and then create users from there.

Authentication modes

Sherpa has two authentication modes. The mode is controlled by environment variables, making it straightforward to run locally without a login wall while enforcing authentication in production.

Mode	How to enable	Behaviour
Compatibility mode (default)	Neither `SHERPA_AUTH_ENABLED` nor `SHERPA_AUTH_DISABLED` is set	All requests are treated as an admin. No login is required. Designed for local development and testing.
Auth mode	`SHERPA_AUTH_ENABLED=1`	Login is required. A session cookie (`sherpa_session`) is issued on successful login. Unauthenticated requests receive HTTP 401 and are redirected to `/ui/login.html`.
Force compatibility	`SHERPA_AUTH_DISABLED=1`	Overrides `SHERPA_AUTH_ENABLED`. Forces compatibility mode even in environments where `SHERPA_AUTH_ENABLED=1` is set.

Roles

Sherpa has two roles. Every user has exactly one.

Role	Permissions
`user`	Chat, conversation history, conversation sharing, personal workspace, source document downloads
`admin`	Everything `user` can do, plus: document-folder registration and ingest, user management, audit log access, knowledge-graph admin screens, Elasticsearch admin search, concept management, world deletion

Initial admin bootstrap

Set the bootstrap password

Add SHERPA_ADMIN_PASSWORD=your-initial-password to your environment file (e.g. /etc/sherpa/sherpa.env). This variable is only used during the first login as admin — it is not the permanent password store. The actual password is stored as a pbkdf2 hash in the database.

Start Sherpa

Start (or restart) the Sherpa service. The bootstrap process runs on first login, not on startup.

Navigate to /ui/login.html and log in with username admin and the password you set in SHERPA_ADMIN_PASSWORD. On first login, Sherpa creates the admin user row in the database and hashes the password. Subsequent logins use the stored hash and ignore the environment variable.

Create your first operational user

Open ユーザー管理 (User Management) and create the accounts your team needs (see Creating a user below). Assign admin roles to those who need ingest or audit access.

Review SHERPA_ADMIN_PASSWORD handling

After the initial bootstrap, decide whether to leave SHERPA_ADMIN_PASSWORD in the environment. Since the actual password is now stored in the database, the variable only triggers a re-bootstrap if the admin row loses its password hash. Remove or rotate it according to your security policy.

User management

Creating a user

In the admin navigation, click ユーザー管理 (User Management).
Fill in the ユーザー名 (username / uid), 表示名 (display name), 役割 (role), and 初期パスワード (initial password) fields.
Click 追加 (Add).

POST /admin/users
Content-Type: application/json

{
  "uid": "alice",
  "display_name": "Alice Tanaka",
  "role": "user",
  "password": "initial-password"
}

The uid field must match the slug pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. This constraint is enforced at both the API layer and by a database CHECK constraint (users_uid_format). Null values are also rejected.Valid role values are "user" and "admin".

The uid is the stable key that binds a user to their conversations, shared links, personal workspace files, and audit log entries. It cannot be changed after creation. Choose a uid that will remain meaningful if the user’s email or display name changes in the future.

Disabling a user

Users are disabled, not deleted. Disabling a user prevents login immediately but preserves all their data — conversations, workspace files, and audit history remain intact and can be reviewed by admins. A disabled user can be re-enabled at any time.

On the ユーザー管理 screen, click the disable button next to the user’s row and confirm.

PATCH /admin/users/{uid}
Content-Type: application/json

{ "status": "disabled" }

To re-enable:

PATCH /admin/users/{uid}
Content-Type: application/json

{ "status": "active" }

An admin cannot disable their own account. The API returns HTTP 403 with reason self_disable if this is attempted, and the event is recorded in the audit log.

Resetting a password

On the ユーザー管理 screen, click パスワード再設定 (Reset Password) next to the target user and enter the new password.

PATCH /admin/users/{uid}
Content-Type: application/json

{ "password": "new-password" }

Changing a role

PATCH /admin/users/{uid}
Content-Type: application/json

{ "role": "admin" }

Role promotions to admin are recorded in the audit log with severity critical.

Listing users

GET /admin/users

Returns all users with their uid, display name, role, status, and creation timestamp.

Audit log

The audit log records every significant action taken in Sherpa. It is append-only and protected by a hash chain.

What is recorded

Category	Events
Authentication	Login (success and failure), logout
User management	User created, user disabled/re-enabled, role changed, password reset
Conversation sharing	Share created, share denied (contains personal workspace), share accepted, share revoked
Personal workspace	File uploaded, file deleted
Document access	Source document downloaded
Settings	Settings updated
World operations	World deletion requested (pre-event), world deleted (post-event)
Audit log	Audit log viewed (`admin.audit_viewed`), audit chain verified (`admin.audit_verified`)

Viewing the audit log

In the admin navigation, click 監査ログ (Audit Log). Use the filter controls to narrow results by actor, action, outcome, severity, or time range.

GET /admin/audit

All parameters are optional query strings:

Parameter	Description
`actor`	Filter by the uid of the user who performed the action
`action`	Filter by action name (e.g. `user.created`, `admin.audit_viewed`)
`resource_type`	Filter by resource type (e.g. `user`, `world`, `audit_log`)
`resource_id`	Filter by specific resource identifier
`outcome`	Filter by result: `success`, `deny`, `error`, `failure`
`severity`	Filter by severity level: `info`, `warning`, `critical`
`time_from`	Start of time window (ISO 8601)
`time_to`	End of time window (ISO 8601)
`request_id`	Filter by request correlation ID
`limit`	Number of rows to return (1–500, default 100)
`offset`	Pagination offset (default 0)

Viewing the audit log is itself recorded as an admin.audit_viewed event with severity critical. This is a fail-closed operation: if Sherpa cannot write the audit entry, the log view request is rejected with HTTP 500 rather than silently exposing the log without a record. The same fail-closed behaviour applies to admin.audit_verified.

Hash-chain integrity

Every audit entry contains two hash fields:

prev_hash — the SHA-256 hash of the previous entry in the chain.
entry_hash — the SHA-256 hash of the current entry’s content combined with prev_hash.

These are computed inside a transaction with an advisory lock, ensuring that concurrent audit writes do not produce inconsistent chain links.

Verifying the chain

GET /admin/audit/verify

The response includes ok: true if the chain is intact, or ok: false with a broken_at field identifying the first anomalous row ID if tampering is detected. The verify endpoint detects:

Anomaly	Detection method
Row content modified	`entry_hash` mismatch
Rows reordered	`prev_hash` sequence break
Rows deleted from the end (truncation)	Chain head anchor mismatch
Null / injected rows inserted after chain start	Missing `entry_hash` or sequence gap
Chain head record missing	Anchor absence

The hash-chain anchor is stored in the same database as the audit entries. A database superuser with direct write access to both tables could in principle modify both the entries and the anchor without detection by GET /admin/audit/verify. For environments where the database administrator is not fully trusted, external signing or periodic export to an append-only log store is recommended as an additional layer. This is a planned enhancement and is not yet built into Sherpa.

Getting Started

Using Sherpa

Administration

Deployment

Managing users and reviewing the audit log in Sherpa

Authentication modes

Roles

Initial admin bootstrap

User management

Creating a user

Disabling a user

Resetting a password

Changing a role

Listing users

Audit log

What is recorded

Viewing the audit log

Hash-chain integrity

Verifying the chain

Build docs developers (and LLMs) love

Getting Started

Using Sherpa

Administration

Deployment

Documentation Index

​Authentication modes

​Roles

​Initial admin bootstrap

​User management

​Creating a user

​Disabling a user

​Resetting a password

​Changing a role

​Listing users

​Audit log

​What is recorded

​Viewing the audit log

​Hash-chain integrity

​Verifying the chain

Build docs developers (and LLMs) love

Authentication modes

Roles

Initial admin bootstrap

User management

Creating a user

Disabling a user

Resetting a password

Changing a role

Listing users

Audit log

What is recorded

Viewing the audit log

Hash-chain integrity

Verifying the chain