Metrics and service tokens

Bridge serves two read-only endpoints for monitoring:

Endpoint	What it reports
`GET /api/stats`	Aggregate session statistics, derived from the recordings on disk.
`GET /api/cluster`	Live topology: roles, worker health, the leader lease, and a count of active sessions.

/api/stats is what the Admin console’s Overview tab reads. /api/cluster answers the question a monitoring system actually asks about a cluster: are the workers there, are they healthy, and is anything draining.

A service token is a named, read-only credential for that endpoint and nothing else. Use one instead of the cluster token. The cluster token reaches every administrative endpoint, including creating a checkout, which grants privileged access to a target. It is also the secret cluster members authenticate to each other with, so revoking it breaks the cluster.

Create a service token

Open the Admin console from the floating button in the web interface.
Go to the Service Tokens tab.
Enter a name that says which system will use it, such as prometheus.
Select Create.
Copy the token from the panel that appears.

Bridge stores only a hash of the token, so the value shown at creation is the only copy. If you navigate away without copying it, revoke it and create another.

Scrape the endpoint

Send the token in the X-Bridge-Service-Token header:

terminal

curl -H "X-Bridge-Service-Token: $TOKEN" https://bridge.example.com/api/stats

For Prometheus, request the text exposition format. Both endpoints support it:

terminal

curl -H "X-Bridge-Service-Token: $TOKEN" \
  "https://bridge.example.com/api/stats?format=prometheus"

curl -H "X-Bridge-Service-Token: $TOKEN" \
  "https://bridge.example.com/api/cluster?format=prometheus"

What the cluster endpoint reports

The gauges from /api/cluster?format=prometheus:

Series	Meaning
`bridge_cluster_workers`	Registered session and proxy workers.
`bridge_cluster_workers_healthy`	Workers whose last heartbeat is inside the staleness window.
`bridge_cluster_workers_draining`	Workers draining before they exit.
`bridge_cluster_active_sessions`	Active sessions, over the scope named by the `scope` label.
`bridge_cluster_leader_held`	`1` when a control-plane leader lease is held and unexpired.
`bridge_cluster_worker_active`	Sessions each worker reports serving, labelled by `worker` and `role`.
`bridge_cluster_worker_max_concurrent`	Sessions each worker accepts at once, same labels.

Alert on bridge_cluster_workers_healthy falling below what the orchestrator is configured to keep, and on bridge_cluster_leader_held reaching 0 for longer than the lease duration. Compare bridge_cluster_worker_active against bridge_cluster_worker_max_concurrent to see saturation rather than infer it.

Read the scope label on bridge_cluster_active_sessions. It is cluster when the count came from the shared registry and covers every node, and instance when it covers only the process that answered. Behind a load balancer an instance count depends on which replica served the scrape and moves between scrapes for that reason alone. Bridge labels it rather than hiding it, so a dashboard cannot quietly present a per-process number as a fleet-wide one.

The token works in the header only. Passing it as a query parameter does not authenticate. An edge proxy logs full request URIs, so a token in the URL would be written to its access logs in cleartext.

What a service token cannot do

A service token reaches counts and topology. Neither endpoint returns session identifiers, user names, target hosts, client addresses, or recordings.

That is why /api/cluster exists as its own endpoint rather than as a wider permission on the Admin console’s cluster view. The console’s version of the same screen lists every active session with the user and the target it reaches, which is the one thing a scraping credential must never hold. /api/cluster reports the same infrastructure and a count. The admin endpoint stays admin-only.

A service token also cannot create another service token. Minting one is an administrative operation, so a leaked scraping credential cannot widen its own access.

Rotate a token

Create the replacement first, move the monitoring system onto it, then revoke the old one.

Bridge allows one live token per name, so rotating in that order lets you keep the name. Revoking first and then creating also works. Creating a second token under a name already in use is refused, and the message says to revoke the existing one or choose another name.

Revoke a token

Open the Service Tokens tab.
Select Revoke beside the token.

The revocation applies on the next request, across every node in the deployment. Bridge verifies a presented token against the datastore rather than against a copy loaded at startup, so nothing needs restarting.

A revoked token stays in the list, marked, so the record shows that a credential was withdrawn and when.

The per-process session count is absent from `/api/stats` output

/api/stats omits an active-session gauge. The count it holds is in-memory state for one process, so behind a load balancer it would report whichever replica answered and jump between scrapes.

/api/cluster answers this properly instead: it reads the shared registry when one is available, which makes the count fleet-wide, and labels the result with its scope either way so you can tell.

Last updated on August 18, 2026