Agent mode: how PWR talks to the Collector, securely
6 min read
A simple explanation of what happens when you choose the local Collector connection: why a dedicated token (X-Collector-Token) rather than your usual login, and how PWR always knows who is talking to it — you, or the agent installed at your site.
What to remember in one sentence
When you choose Agent mode (local Collector) rather than a direct connection, PWR never talks to your database itself: it sends its request to the Collector agent installed at your site, and it is the Collector that actually queries PostgreSQL before returning the result.
For this exchange to stay reliable and secure, PWR uses two completely separate identities: your login (which proves that it really is you, the user, viewing a report) and a technical token belonging to the Collector (which proves that it really is your agent, and not a third party, answering). These two identities never mix.
Why the Collector needs its own token
The Collector is not a person: it has no account, no password, no login session like a user connecting to PWR. It is a small program installed on a machine in your infrastructure, whose only role is to run read-only queries on PWR's behalf and return the result.
Yet PWR must be certain of two things before sending any request: that it is indeed addressing YOUR agent (and not a third-party machine impersonating it), and that this agent is still authorized to respond (the token can be revoked or regenerated at any time from your "Connections" area). That is exactly the role of the dedicated token sent with every call.
Two tokens, two roles, never confused
When you view a report in your browser, your PWR session (created at login) proves to the SaaS that it is really you. That token never leaves PWR's servers: it is neither transmitted to, nor known by, the Collector.
When PWR needs data that lives at your site (the "Live" dashboard, the snapshot history, a comparison report...), it sends a second, separate request to your Collector agent — this time accompanied by the token belonging to that agent, different for each client and regenerable at will.
Result: your personal session and your Collector's identity never cross paths in the same exchange. A problem with one (expired session, revoked Collector token) never affects the validity of the other.
Concrete example: opening the "Live" dashboard
Here is what concretely happens, in three steps, when you open the real-time dashboard with a connection in Agent mode:
1. Your browser requests the data from the PWR SaaS, using your usual personal session — exactly as for any other page in the application.
2. The PWR SaaS relays this request to your Collector, attaching the token dedicated to this specific connection — never your personal session, which the Collector has no way to verify anyway.
3. The Collector verifies this token, queries your PostgreSQL database read-only, and immediately returns the result to the SaaS, which displays it in your dashboard.
At no point does your password, your session or your personal credentials travel to the agent installed at your site: it only ever knows its own token, generated and shown once during its setup.
Why not simply reuse the same token everywhere?
You might imagine something simpler: a single token for everything. That would actually be riskier, for two reasons.
First, a user session token is personal and temporary (it expires, it can be renewed at each login) — poorly suited to an agent that must stay reachable continuously, sometimes for months, without a user ever logging back in. Conversely, the Collector's token is designed to last, but remains independently revocable at any time, without ever disconnecting the users on your team.
Second, separating the two strictly limits what a compromised token could do: if the Collector's token leaked, it would only grant access to that specific connection's read-only data — never to your account, your other connections, or your workspace settings.
How PWR knows which Collector to call
Each connection in Agent mode records, on PWR's side, the address at which to reach your Collector as well as its own token — visible and editable at any time from "Connections" > "Configure the agent". Regenerating the token from this screen immediately invalidates the old one: the already-installed agent will need to be reconfigured with the new value before it can respond again.
It is this association (one connection = one address + one token, specific to that client) that lets PWR manage several clients in Agent mode in parallel, each with its own Collector, without ever risking mixing up their data.
In summary
Your user session proves who you are to PWR. The Collector's token proves to PWR that it really is your agent answering. The two live in separate worlds, never cross paths in the same exchange, and can be revoked independently — which is what lets Agent mode stay as secure as a direct connection, while keeping your PostgreSQL database out of Internet's reach.