ComAp WebSupervisor Cloud API — the two-key auth, the hour-long token, and the listing method ComAp's own docs disagree on

WebSupervisor is ComAp's cloud platform for monitoring and controlling generator-set (genset) controllers in the field, and its Cloud API is how fleet-management software pulls live and historical telemetry programmatically. The API itself is a plain REST surface behind Azure API Management — but it sits behind a two-step identity flow with three separate credentials, requires two auth headers on every data call, hands out tokens that die in an hour while secrets live two years, and lists your units at an endpoint whose HTTP method ComAp's own sources disagree on — the portal's sample says POST, the official-API Python wrapper sends GET. These are the documented steps and failure modes from Waymark's live route corpus, checked against ComAp's official Cloud API developer portal and the wrapper's published source.

Why this integration surprises agents

Three structural facts drive most first-attempt failures. First, there is no single API key: you authenticate to the ComAp Cloud Identity service with a client_id and secret (from an application registration) plus your ComAp-Key subscription key, and only the resulting Bearer token — sent together with the same Comap-Key header — gets you into the WSV data APIs. Second, the credentials age at wildly different rates: the Bearer token's documented expires_in is 3599 seconds, while the client_id/secret pair is valid for two years — ComAp publishes a dedicated guide for refreshing expired secrets, and long-running integrations that never planned for either expiry fail at both timescales. Third, the account tier is a hard gate: per the official portal, the API is available in 3-month Trial accounts or Pro accounts — if the site runs a basic WebSupervisor account, no credential fixes that.

Verified route for this task

The procedure

1. Confirm the account tier. Per ComAp's developer portal, the Cloud API is available in 3-month Trial accounts or all Pro accounts — verify this before writing any code
2. Register a ComAp Cloud Identity, then register an application (ComAp publishes official step-by-step PDF guides for both on the portal home page). The application registration yields your client_id and secret — documented as valid for 2 years
3. Copy the ComAp-Key subscription key from your Profile at portal.websupervisor.net. The same key authenticates you to both the Identity API and the WSV data APIs
4. Exchange client_id + secret + ComAp-Key for a Bearer token via the Identity API. The response's expires_in is 3599 seconds — cache the token and plan an hourly refresh, not a per-call re-auth
5. Call the WSV API with both headers on every request: Authorization: Bearer <token> and Comap-Key: <subscription key>. List your controllers at /v1.1/{loginId}/units on api.websupervisor.net — {loginId} is the WSV account user name (one identity can own several). ComAp's portal sample labels this call POST, but the official-API Python wrapper sends GET and is the working reference — if one method comes back 404/405, try the other before touching credentials
6. Pull telemetry per unit: each unit has a unitGuid (genset…); values are filterable by a comma-separated valueGuids query parameter (call once unfiltered to discover the GUIDs — values are addressed by GUID, not name), and history takes from/to query parameters with dates documented in US MM/DD/YYYY format
7. Remote control uses the documented commands start, stop, faultReset, changeMcb, changeGcb, changeMode (with a mode like man/auto) — these act on physical generators; treat them as high-risk writes behind stricter authorization

# Community wrapper (PyPI 'comap', MIT, Python ≥3.11 — async module recommended for production)
pip install comap

from comap import api

# 1. Identity: ComAp-Key + client_id + secret → Bearer token (expires_in: 3599)
identity = api.Identity(COMAP_KEY)
token = identity.authenticate(CLIENT_ID, SECRET)

# 2. WSV: same ComAp-Key again, plus the token, plus your WSV login
wsv = api.WSV(LOGIN_ID, COMAP_KEY, token["access_token"])
for unit in wsv.units():                      # /v1.1/{loginId}/units — wrapper sends GET
    print(unit["unitGuid"], unit["name"])     # (portal sample says POST; see gotcha above)

# Values: filter by valueGuids or fetch all once to discover them
# History: wrapper args _from/_to map to REST params from/to, dates MM/DD/YYYY
history = wsv.history(unit_guid, "07/01/2026", "07/12/2026", value_guids)

The endpoint map, from the wrapper's source

The official portal renders its API reference behind JavaScript and sign-in, so the fastest verifiable endpoint map is the official-API wrapper's published constants (PyPI comap 0.3.2). Identity: POST https://api.websupervisor.net/identity/application/authenticate with JSON body {"clientId": …, "secret": …} plus the Comap-Key header. Data (all under https://api.websupervisor.net/v1.1/{loginId}/): units, and per unit units/{unitGuid}/values, /info, /history, /files, /comments, /command (POST, body {"command": …, "mode": …}). One trap: file download uses unit — singular — in the path: /v1.1/{loginId}/unit/{unitGuid}/download/{fileName}. An agent that pattern-matches the plural units/… shape of every other endpoint will 404 here.

The on-prem trap

WebSupervisor also exists as locally deployed installations, and the Cloud API endpoints don't apply to them. Before assuming portal.websupervisor.net credentials and cloud endpoints, confirm the specific site actually runs the cloud product — an integration built against the cloud surface has nothing to talk to on an on-prem deployment, and the failure looks like an auth problem when it's actually a product-line mismatch.

Control commands are physical-world writes

The command set — start, stop, faultReset, changeMcb (toggle mains circuit breaker), changeGcb (toggle genset circuit breaker), changeMode — starts and stops real generators and toggles real breakers. These calls are higher-privilege than read-only telemetry and sit behind stricter authorization scopes. An agent wired for autonomous fleet monitoring should treat them the way it treats payment writes: gated, confirmed, and never retried blindly.

How agents avoid this automatically

Agents wired to Waymark's MCP server pull this route (the two-step identity flow, the dual headers, the token-vs-secret lifetimes, the POST-based listing, the account-tier gate) at plan time instead of reverse-engineering ComAp's credential model from PDF guides — and instead of discovering the Trial/Pro gate after the code is written. Reads are free and keyless.

# Any MCP client — one call, no key:
waymark_query({ "task": "ComAp WebSupervisor cloud API generator monitoring" })

# Or plain HTTP:
curl -s "https://mcp.waymark.network/search?q=ComAp%20WebSupervisor%20cloud%20API"