SSH Sessions

SSH session metadata is recorded for audit and troubleshooting. When ssh_recording is enabled in the server config, session stdout is also captured in chunks for playback.

List SSH Sessions

GET /api/v1/ssh/sessions
GET /api/v1/ssh/sessions?limit=50&offset=0

List SSH sessions. Admins see all sessions; operators see only their own sessions.

Query parameters:

• router_id (optional) — Filter by the target device's router ID (exact match)
• protocol (optional) — Filter by ssh or telnet
• from / to (optional) — RFC3339 bounds on started_at
• limit (optional) — Maximum number of sessions to return (default: 50, max: 1000). Values outside that range are clamped, and the response echoes the clamped value, so offset += limit paging stays correct.
• offset (optional) — Number of sessions to skip for pagination (default: 0). Negative values are treated as 0.

Response: 200 OK

{
  "sessions": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "username": "admin",
      "device_router_id": "10.0.0.1",
      "device_hostname": "router1",
      "protocol": "ssh",
      "client_ip": "198.51.100.20",
      "started_at": "2026-02-17T10:30:00Z",
      "ended_at": "2026-02-17T10:45:00Z",
      "bytes_sent": 4096,
      "bytes_received": 65536
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}

Field notes:

• username is the Osprey login that opened the session, joined from app_user — it is not a column on ssh_session. Always present. It reflects the account's current name: renaming a user rewrites the attribution on their historical sessions.
• device_hostname is omitted when no hostname was recorded for the device (the column is nullable, and rows with an empty hostname exist). Clients must fall back to device_router_id.
• ended_at is omitted while the session is still active.
• protocol reflects the transport actually used, including a telnet fallback recorded after the session row was created.

Get SSH Session

GET /api/v1/ssh/sessions/{sessionID}

Get a single SSH session by ID. Admins can view any session; operators can only view their own.

Response: 200 OK (single session object)

Error responses:

• 403 Forbidden — Operator attempting to view another user's session
• 404 Not Found — Session does not exist

Get SSH Session Log

GET /api/v1/ssh/sessions/{sessionID}/log

Get the session stdout log as an ordered array of recording chunks. Only available when session recording is enabled (ssh.session_recording) and the session has recorded data; otherwise the array is empty. Chunks are decrypted server-side when OSPREY_ENCRYPTION_KEY is configured.

Response: 200 OK — a flat array (not an envelope); concatenate data in chunk_index order.

[
  {
    "id": "uuid",
    "session_id": "uuid",
    "chunk_index": 0,
    "data": "base64-encoded-stdout-data",
    "recorded_at": "2026-02-17T10:30:01Z"
  }
]

Error responses:

• 403 Forbidden — Operator attempting to view another user's session log
• 404 Not Found — Session does not exist or no recording available