Firezone Session Logs | Firezone Docs

Session Logs

Session Logs record who connected to Firezone, from where, and when. They are the starting point for access reviews and incident timelines: verifying an unfamiliar sign-in location, confirming that a deprovisioned user no longer connects, or establishing which devices were connected during a given window.

Every session established in your account records one entry, and the context field tells you which kind of session it was:

client: A Client device connected to Firezone. An entry is recorded each time the Client opens its WebSocket connection to the control plane, so a device that reconnects after waking from sleep, switching networks, or a network interruption produces a new entry for each connection rather than one per sign-in.
gateway: A Gateway connected to Firezone. As with Clients, an entry is recorded for each WebSocket connection the Gateway opens to the control plane.
portal: An admin signed in to the admin portal. The entry is written in the same database transaction as the sign-in itself, so a portal login cannot succeed without its audit record.

Log IDs

Session Log IDs start with 5, and because the bits after the stream character are random, they carry no ordering meaning. Order entries by timestamp instead.

Fields

Field	Description
`log_id`	Unique ID of the entry.
`timestamp`	When the session was established.
`context`	One of `client`, `gateway`, or `portal`.
`subject`	Who connected and from where, described below.

How the subject is tracked

The subject is a snapshot taken when the session is established. Entries stay intact even if the actor, device, or token is later deleted, so the audit trail is preserved across offboarding and cleanup. The subject's shape depends on the context.

Client and portal sessions are attributed to an actor:

Key	Description
`actor_id`	ID of the actor that connected.
`actor_name`	Display name of the actor.
`actor_email`	Email of the actor.
`actor_type`	`account_admin_user`, `account_user`, or `service_account`.
`auth_provider_id`	The authentication provider used to sign in.
`ip`	Source IP address of the connection.
`ip_region`	ISO 3166 country code resolved from the IP.
`ip_city`	City resolved from the IP.
`ip_lat`, `ip_lon`	Coordinates resolved from the IP.
`user_agent`	User agent of the Client or browser.

Client sessions also include device_id for the device that connected and token_id for the Client token used.

Gateway sessions have no actor, because Gateways authenticate with a Gateway token. Their subject contains gateway_id, token_id, and the same ip, ip_region, ip_city, ip_lat, ip_lon, and user_agent connection context.

The location fields are resolved from the connection's source IP using MaxMind's GeoLite2 City database when the entry is recorded, and the portal surfaces them as a Location column on every entry along with a location map in the detail panel, which makes unusual sign-in locations easy to spot.

Example

A Client connecting to the control plane:

{
  "type": "session",
  "log_id": "53f2c8a91b7e4d20a6c19e04",
  "timestamp": "2026-07-14T09:26:31.114213Z",
  "context": "client",
  "subject": {
    "actor_id": "7a1d9e3c-5b2f-4c8d-9e0f-1a2b3c4d5e6f",
    "actor_name": "Riley Engineer",
    "actor_email": "riley@company.com",
    "actor_type": "account_user",
    "auth_provider_id": "9d0c2f4e-8b6a-4c2d-8e1f-3a5b7c9d0e2f",
    "device_id": "2b4d6f8a-0c1e-4a3b-8d5f-7e9a1c3b5d7f",
    "token_id": "c4e6a8b0-2d4f-4e6a-9c8b-0d2f4e6a8c0b",
    "ip": "203.0.113.44",
    "ip_region": "US",
    "ip_city": "San Francisco",
    "ip_lat": 37.7749,
    "ip_lon": -122.4194,
    "user_agent": "Firezone/1.4.0 (macOS 15.5; arm64)"
  }
}

Viewing and retention

Session Logs live under Logs→Session Logs in the admin portal. You can also query them via the REST API's /logs endpoint with type=session. Entries are kept for 90 days.