Ciresk Docs
API reference

Connections

The connection log: who reached which session, from which device, by which stream.

GET/v1/dev/connections

List connections

The connection log, oldest first - who reached which session, from which device, by which kind of stream, with how many bytes and why streams closed.

One row per window the worker reports: the verified tunnel streams of one grant, kind, port and client over about a minute, ping excepted. A window that opened a stream is also a dev.tunnel.connect record of the audit log. principal matches a row's person or its agent; since and until keep the windows that overlap them. A worker released before reports no windows. An audit read, a person's or a service's: an agent principal is refused 403 principal_not_allowed, and dev_connections_list serves an agent that runs under its person's credential, reading what that person may.

Permission: dev:audit.read

Parameters

NameTypeRequiredDescription
cursorquerystringOptional
limitqueryintegerOptional
session_idquerystringOptional
principalquerystringOptionala subject, user:<id> or agent:<id>
sincequerystring (date-time)Optionalwindows that end at or after this moment
untilquerystring (date-time)Optionalwindows that start before this moment

Response200 OK

dataarray of objectsRequired
data[].activeintegerRequired
streams still open at its end
data[].agentstring or null
the verified agent identity, agent:<id>, when an agent acted
data[].bytes_downintegerRequired
bytes the worker sent in the window
data[].bytes_upintegerRequired
bytes the worker received in the window
data[].clientstringRequired
the client label, mcp:<pid>[:<agent>], cli, browser
data[].closedintegerRequired
streams closed in the window
data[].devicestringRequired
the device key's fingerprint
data[].fromstring (date-time)Required
data[].grantstringRequired
data[].kindstringRequired
the stream kind's ticket name: tcp, sync, exec, ssh, ssh_ro, logs, browser,...
data[].openedintegerRequired
streams opened in the window
data[].portinteger or null
a tcp stream's port
data[].principalstringRequired
the ticket's principal, the person answerable: user:<id>
data[].reasonsmap of integerRequired
why the closed streams ended, with counts: closed, or a failure code
data[].seqintegerRequired
the row's place in the log
data[].session_idstringRequired
data[].tostring (date-time)Required
data[].workerstringRequired
has_morebooleanRequired
next_cursorstring or null

Errors

curl "$CIRESK_API/v1/dev/connections" \
  -H "Authorization: Bearer $CIRESK_KEY"