Webroot API Patterns
Overview
The Webroot MCP server is a read-only view of one MSP's GSM console (Global Site
Manager) through the Webroot Unity API. The hierarchy is GSM console > sites (one per
customer) > groups > endpoints. Every tool is a GET; nothing can issue agent
commands or change configuration.
Authentication through Conduit
Conduit stores the credential once, entered in the Conduit web UI (/connect/webroot),
and sends five headers on every call. Nothing is set on the client, and Conduit drops any
X-Webroot-* header a client sends:
| Header |
Conduit field |
X-Webroot-Client-Id |
API client ID |
X-Webroot-Client-Secret |
API client secret |
X-Webroot-Username |
Console username (email) |
X-Webroot-Password |
Console password |
X-Webroot-Gsm-Key |
GSM key (parent keycode) |
The server exchanges these for a short-lived Unity API token (about five minutes) and
refreshes it itself. A 401 from Webroot gets one fresh token and one retry, so a
401 that reaches you means the credential itself is wrong or the console user was
disabled or had its password changed.
The API acts as the console user. That user's role and site permissions decide what
comes back: a site the user cannot see is simply missing from webroot_sites_list, not
an error.
The GSM key is never a tool argument. It is bound to the connection, so one Conduit
connection always reads one GSM console.
Connection test
webroot_health_ping: is the Unity API reachable? Uses no credentials, so it proves
nothing about the connection.
webroot_console_get: the real authenticated test. Returns the console name, license
type, seats allowed, site counts and end date.
Tool surface and Conduit access groups
All 25 tools are read-only. Conduit puts 21 in its Read group and 4 in its Admin
group. A user granted only Read on the Webroot connection cannot call the Admin tools;
confirm the live grant in Conduit's access editor.
| Conduit group |
Tools |
| Read |
webroot_health_ping, webroot_console_get, webroot_statistics_console_get, webroot_sites_list, webroot_sites_get, webroot_sites_lookup, webroot_statistics_site_get, webroot_endpoints_list, webroot_endpoints_get, webroot_groups_list, webroot_groups_list_endpoints, webroot_policies_list, webroot_policies_list_site, webroot_threats_list_site, webroot_threats_list_endpoint, webroot_blockedurls_list, webroot_dnsp_traffic_summary, webroot_dnsp_blocked_list, webroot_agent_status_gsm, webroot_agent_status_site, webroot_usage_sites_report |
| Admin |
webroot_commands_list_site, webroot_commands_list_endpoint (agent command audit history), webroot_admins_list, webroot_admins_list_site (admin names, emails, phone numbers) |
If an Admin tool is refused, say the user needs Admin access to Webroot in Conduit.
Do not retry or work around it.
Identifiers
| You have |
You need |
Tool |
| A customer name |
siteId |
webroot_sites_list (not paginated; returns every site) |
| A site keycode (from an agent, an installer or an invoice) |
siteId |
webroot_sites_lookup |
A siteId |
The site keycode |
webroot_sites_get (the AccountKeyCode field) |
| A hostname |
endpointId |
webroot_endpoints_list with hostName |
| A group name |
groupId |
webroot_groups_list |
Two tools take the site keycode, not the siteId: webroot_agent_status_site and
webroot_sites_lookup. Everything else per-site takes the siteId GUID.
Pagination
Three styles, depending on the tool. Each call makes one request; page until done
before saying something does not exist.
| Style |
Tools |
How to continue |
PageNr + TotalAvailable |
webroot_endpoints_list, webroot_groups_list_endpoints, webroot_commands_list_site, webroot_commands_list_endpoint |
Request pageNr + 1 until you have TotalAvailable records |
PageNr + MoreAvailable |
webroot_threats_list_site, webroot_threats_list_endpoint, webroot_blockedurls_list, webroot_dnsp_blocked_list |
Request pageNr + 1 while MoreAvailable is true |
ContinuationToken |
webroot_agent_status_gsm, webroot_agent_status_site |
Pass the returned ContinuationToken as continuation; no token means the last batch |
Page size limits: pageSize defaults to 50 on endpoints, threats and commands;
webroot_blockedurls_list takes 50 to 1000 (default 100); webroot_dnsp_blocked_list
takes 100 to 10000 (default 1000); agent status batchSize takes 1 to 1000 (default 50).
Values above a maximum are capped, not rejected.
For agent status, pass only the returnedInfo classes you need (BasicInfo,
ExtendedInfo, TimesAndStats, Scheduling, EnabledFeatures, SystemAnalyzer,
OSAndVersions). Omitting it returns every class and fills the response fast.
Dates
Threat, URL and DNS tools default to the last 24 hours when you pass no dates. For a
monthly review, pass startDate and endDate explicitly as ISO 8601 date-times
(2026-10-01T00:00:00Z). Say which window a result covers; "no threats" over the default
window is not "no threats this month".
webroot_usage_sites_report data for a day is usually ready during the following UTC
day; asking for today returns the most recent complete report or nothing.
Errors
Errors keep Webroot's HTTP status, error code, description and request id. Quote the
request id when escalating to Webroot support.
| Status |
Meaning |
What to do |
| 401 |
Credential rejected even after a fresh token |
Re-check the client ID/secret and the console login; reconnect Webroot in Conduit |
| 403 |
The console user or API client lacks the scope or site permission |
The console user's role or site access is too narrow for this call |
| 404 |
Unknown site, endpoint or group ID |
Re-list; IDs are GUIDs and are per site |
| 429 |
Rate limited |
Wait for the Retry after value in the error, then continue more slowly |
| Redirect refused |
Webroot answered with a 3xx |
The server never follows redirects; retry later, then report it |
| Response exceeded the size limit |
Body over 4 MiB |
Lower pageSize/batchSize or shorten the date range |
Webroot does not document rate limits. Prefer paging over maximum page sizes, and do not
fan out per-endpoint calls across every site at once.
Gotchas
webroot_sites_list is the only full-console site list. It is not paginated, so
one call returns every site the console user can see.
- Statistics are point-in-time.
webroot_statistics_console_get and
webroot_statistics_site_get are current counts, not history. Use the threat tools for
anything over time.
- Deactivated and hidden endpoints.
webroot_endpoints_list returns active and
deactivated endpoints unless you pass type. webroot_blockedurls_list excludes
deactivated and hidden endpoints unless you set includeDeactivated /
includeHidden.
- Redacted output. Credentials and token-shaped strings are redacted from responses,
and long responses are truncated in a way that keeps the paging fields.
Related Skills
1---2name: webroot-api-patterns3description: >4 Webroot Unity API fundamentals through Conduit: the five X-Webroot-* headers5 and the console-user password grant behind them, the GSM key bound to the6 connection, the 25 read-only tools and which four Conduit admin-gates, the7 three paging styles (PageNr/TotalAvailable, PageNr/MoreAvailable,8 ContinuationToken), siteId vs. site keycode, date-range defaults, error9 statuses, and response size limits.10when_to_use: >-11 When connecting to Webroot through Conduit, paging a Webroot list, or12 diagnosing a failed Webroot tool call. Use when: webroot api, webroot13 authentication, webroot 401, webroot 403, webroot pagination, gsm key,14 site keycode, unity api, or webroot connection test.15metadata:16 source: https://skillmd.com/skills/wyre-ai/webroot-api-patterns17---1819# Webroot API Patterns2021## Overview2223The Webroot MCP server is a read-only view of one MSP's **GSM console** (Global Site24Manager) through the Webroot Unity API. The hierarchy is GSM console > sites (one per25customer) > groups > endpoints. Every tool is a `GET`; nothing can issue agent26commands or change configuration.2728## Authentication through Conduit2930Conduit stores the credential once, entered in the Conduit web UI (`/connect/webroot`),31and sends five headers on every call. Nothing is set on the client, and Conduit drops any32`X-Webroot-*` header a client sends:3334| Header | Conduit field |35|---|---|36| `X-Webroot-Client-Id` | API client ID |37| `X-Webroot-Client-Secret` | API client secret |38| `X-Webroot-Username` | Console username (email) |39| `X-Webroot-Password` | Console password |40| `X-Webroot-Gsm-Key` | GSM key (parent keycode) |4142The server exchanges these for a short-lived Unity API token (about five minutes) and43refreshes it itself. A `401` from Webroot gets one fresh token and one retry, so a44`401` that reaches you means the credential itself is wrong or the console user was45disabled or had its password changed.4647The API acts **as the console user**. That user's role and site permissions decide what48comes back: a site the user cannot see is simply missing from `webroot_sites_list`, not49an error.5051The GSM key is never a tool argument. It is bound to the connection, so one Conduit52connection always reads one GSM console.5354## Connection test5556- `webroot_health_ping`: is the Unity API reachable? Uses no credentials, so it proves57 nothing about the connection.58- `webroot_console_get`: the real authenticated test. Returns the console name, license59 type, seats allowed, site counts and end date.6061## Tool surface and Conduit access groups6263All 25 tools are read-only. Conduit puts 21 in its **Read** group and 4 in its **Admin**64group. A user granted only Read on the Webroot connection cannot call the Admin tools;65confirm the live grant in Conduit's access editor.6667| Conduit group | Tools |68|---|---|69| Read | `webroot_health_ping`, `webroot_console_get`, `webroot_statistics_console_get`, `webroot_sites_list`, `webroot_sites_get`, `webroot_sites_lookup`, `webroot_statistics_site_get`, `webroot_endpoints_list`, `webroot_endpoints_get`, `webroot_groups_list`, `webroot_groups_list_endpoints`, `webroot_policies_list`, `webroot_policies_list_site`, `webroot_threats_list_site`, `webroot_threats_list_endpoint`, `webroot_blockedurls_list`, `webroot_dnsp_traffic_summary`, `webroot_dnsp_blocked_list`, `webroot_agent_status_gsm`, `webroot_agent_status_site`, `webroot_usage_sites_report` |70| **Admin** | `webroot_commands_list_site`, `webroot_commands_list_endpoint` (agent command audit history), `webroot_admins_list`, `webroot_admins_list_site` (admin names, emails, phone numbers) |7172If an Admin tool is refused, say the user needs Admin access to Webroot in Conduit.73Do not retry or work around it.7475## Identifiers7677| You have | You need | Tool |78|---|---|---|79| A customer name | `siteId` | `webroot_sites_list` (not paginated; returns every site) |80| A site keycode (from an agent, an installer or an invoice) | `siteId` | `webroot_sites_lookup` |81| A `siteId` | The site keycode | `webroot_sites_get` (the `AccountKeyCode` field) |82| A hostname | `endpointId` | `webroot_endpoints_list` with `hostName` |83| A group name | `groupId` | `webroot_groups_list` |8485Two tools take the **site keycode**, not the `siteId`: `webroot_agent_status_site` and86`webroot_sites_lookup`. Everything else per-site takes the `siteId` GUID.8788## Pagination8990Three styles, depending on the tool. Each call makes one request; page until done91before saying something does not exist.9293| Style | Tools | How to continue |94|---|---|---|95| `PageNr` + `TotalAvailable` | `webroot_endpoints_list`, `webroot_groups_list_endpoints`, `webroot_commands_list_site`, `webroot_commands_list_endpoint` | Request `pageNr` + 1 until you have `TotalAvailable` records |96| `PageNr` + `MoreAvailable` | `webroot_threats_list_site`, `webroot_threats_list_endpoint`, `webroot_blockedurls_list`, `webroot_dnsp_blocked_list` | Request `pageNr` + 1 while `MoreAvailable` is true |97| `ContinuationToken` | `webroot_agent_status_gsm`, `webroot_agent_status_site` | Pass the returned `ContinuationToken` as `continuation`; no token means the last batch |9899Page size limits: `pageSize` defaults to 50 on endpoints, threats and commands;100`webroot_blockedurls_list` takes 50 to 1000 (default 100); `webroot_dnsp_blocked_list`101takes 100 to 10000 (default 1000); agent status `batchSize` takes 1 to 1000 (default 50).102Values above a maximum are capped, not rejected.103104For agent status, pass only the `returnedInfo` classes you need (`BasicInfo`,105`ExtendedInfo`, `TimesAndStats`, `Scheduling`, `EnabledFeatures`, `SystemAnalyzer`,106`OSAndVersions`). Omitting it returns every class and fills the response fast.107108## Dates109110Threat, URL and DNS tools default to **the last 24 hours** when you pass no dates. For a111monthly review, pass `startDate` and `endDate` explicitly as ISO 8601 date-times112(`2026-10-01T00:00:00Z`). Say which window a result covers; "no threats" over the default113window is not "no threats this month".114115`webroot_usage_sites_report` data for a day is usually ready during the following UTC116day; asking for today returns the most recent complete report or nothing.117118## Errors119120Errors keep Webroot's HTTP status, error code, description and request id. Quote the121request id when escalating to Webroot support.122123| Status | Meaning | What to do |124|---|---|---|125| 401 | Credential rejected even after a fresh token | Re-check the client ID/secret and the console login; reconnect Webroot in Conduit |126| 403 | The console user or API client lacks the scope or site permission | The console user's role or site access is too narrow for this call |127| 404 | Unknown site, endpoint or group ID | Re-list; IDs are GUIDs and are per site |128| 429 | Rate limited | Wait for the `Retry after` value in the error, then continue more slowly |129| Redirect refused | Webroot answered with a 3xx | The server never follows redirects; retry later, then report it |130| Response exceeded the size limit | Body over 4 MiB | Lower `pageSize`/`batchSize` or shorten the date range |131132Webroot does not document rate limits. Prefer paging over maximum page sizes, and do not133fan out per-endpoint calls across every site at once.134135## Gotchas136137- **`webroot_sites_list` is the only full-console site list.** It is not paginated, so138 one call returns every site the console user can see.139- **Statistics are point-in-time.** `webroot_statistics_console_get` and140 `webroot_statistics_site_get` are current counts, not history. Use the threat tools for141 anything over time.142- **Deactivated and hidden endpoints.** `webroot_endpoints_list` returns active and143 deactivated endpoints unless you pass `type`. `webroot_blockedurls_list` excludes144 deactivated and hidden endpoints unless you set `includeDeactivated` /145 `includeHidden`.146- **Redacted output.** Credentials and token-shaped strings are redacted from responses,147 and long responses are truncated in a way that keeps the paging fields.148149## Related Skills150151- [endpoint-health](../endpoint-health/SKILL.md): protection posture triage152- [threat-review](../threat-review/SKILL.md): threat, web and DNS block review153- [usage-reconciliation](../usage-reconciliation/SKILL.md): seats and billing154- [console-audit](../console-audit/SKILL.md): admin access and command history (Admin tools)