list_sessions

Category: auth
Access: read
Audience: administrative (ordinary users do not normally call this directly)

Purpose

Lists server-side session registry entries. Call it to audit live and historical sessions across principals.

Arguments

Optional: client_id, limit, status.

client_id. Note: Narrows to one principal; empty means all.
limit. Note: Defaults 20, clamped 1 to 100.
status. Note: Narrows by active, revoked, expired, or ended; unknown values match nothing.

Result

Object with sessions array (principal, status, generation, timestamps, transport peer, client application/version/instance, revocation state, profile) and count.

Boundaries

Conductor role required. Returns audit metadata only; no key material exists in the registry by construction.

Lifecycle / side effects

Pure registry read; records nothing.

Errors

Non-conductor callers get a requires-conductor error payload. Unknown status values return the empty shape, fail-closed.

Example

{
  "status": "active"
}

Result shape:

{
  "count": 1,
  "sessions": [
    {
      "client_id": "<id>",
      "session_id": "<uuid>",
      "status": "active"
    }
  ]
}