Allowing your monitoring tools and API integrations through CommunityGuard

Applies to: Khoros Communities (Classic and Aurora) protected by CommunityGuard.
Audience: community administrators, monitoring owners, and integration developers.
See also: CommunityGuard FAQ.

---

Who this article is for

CommunityGuard is the intelligence layer in front of your community that tells real visitors apart from automated traffic, and stops AI crawlers, scrapers and attack traffic before they reach the community itself. Because it judges behaviour rather than identity, it can also stop automation that you run on purpose:

• an availability monitor or synthetic test that loads your community pages, or
• a server-to-server integration that calls the Community APIs.

If a tool you operate is being blocked, Khoros Support can grant it a scoped exception. This article explains what the exception does and does not do, what to include in your support case, and how to use the access token you receive.

How to tell your tool is affected

Your tool receives HTTP 403 responses from your community's URL, and the response body is a short verification page rather than the content it asked for. That is CommunityGuard's challenge. Human visitors pass it without noticing because the check runs inside the browser; a script, monitor or API client without a JavaScript engine cannot complete it, so it sees 403 on every request.

A 403 whose body is an ordinary error page, on a request you know is legitimate, can be a web application firewall false positive, for example on a search term or payload that resembles an attack pattern. The same exception covers that case.

An HTTP 429 response is something different. It means your tool is exceeding a rate limit. See What the exception does not change.

The two kinds of exception

Pick the one that matches what your tool calls. A tool that needs both gets both.

	Page access	API access
Use it for	Availability monitors and synthetic tests that load community pages (Dynatrace, Pingdom, Catchpoint and similar)	Server-to-server integrations that call the Community REST or GraphQL APIs
What it covers	Page requests to your community	API requests only: /api/2.0/..., /restapi/..., /api/2.1/graphql
Token header	x-khoros-bot-bypass: <token>	x-khoros-api-access: <token>
IP-based alternative	The monitor's fixed public egress addresses	The integration's fixed public egress addresses
Rate limits	Stay in force	Stay in force

Every exception is scoped to one community, one environment, and one kind of access. Production and staging are separate environments and need separate exceptions. An API access token does not work on page requests. Use the API access token for API calls; page access is not guaranteed to cover API paths.

Token or IP list?

Within either kind of access you can ask for a token, an IP list, or both.

Token is the preferred option whenever your tool can send a custom HTTP header. It works from any address, it survives infrastructure changes on your side, and it can be revoked or replaced on its own. Ask for one token per tool or vendor, so that retiring one integration never affects another.

IP list is for tools that cannot set request headers and always call from fixed public addresses. Entries must be:

• public addresses only; private, loopback and other special-purpose ranges are refused;
• IPv4 only: a single address or a range no wider than /24. IPv6 is not supported;
• addresses used only by the tool in question. Shared corporate proxies, VPN egress, residential connections and generic cloud provider ranges are not accepted, because they would admit traffic that is not yours.

What the exception does

For traffic that matches your token or your listed addresses on that community only, CommunityGuard's challenge, the platform's web application firewall rules and the browser integrity checks are lifted. Everything else about how your community handles the request is unchanged: authentication, API keys, sessions, permissions and content visibility all behave exactly as before.

What the exception does not change

Rate limits. The standard per-address rate limits, the flood protection and the malicious-IP blocklists all stay in force for exempted traffic. If your tool receives HTTP 429, it is exceeding a rate limit, and no exception described here will change that. Open a support case describing the endpoints, the request volume and the schedule your tool needs; Support reviews rate limits separately.

Bulk content retrieval. Exceptions are not available for crawlers, SEO tools (Screaming Frog and similar), content sync or backup scripts, or any job whose goal is to download community content in bulk. Those needs are met through the Khoros data export process instead. Ask Support or your Customer Success Manager about a data export; a request for a CommunityGuard exception for such a tool will be declined.

Policies for named bots. Whether a particular AI service or crawler is allowed, rate-limited or blocked on your community is a CommunityGuard policy decision, not an exception. See the CommunityGuard FAQ.

What to include in your support case

Open a case through the Khoros support portal and include:

1. Your community URL and environment (production or staging).
2. Which kind of access: page access or API access. If both, say so; Support files them separately.
3. What the tool is: the product or vendor name and, in a sentence, what it does. Support needs to see that it is a monitor or an integration, not a crawler.
4. Token, IP list, or both.
5. For an IP list: the addresses or ranges to add, and any existing ones to remove.
6. Evidence of the block: one sample failing request, with the full URL, the timestamp including time zone, the status code, the first lines of the response body, and the source IP address if you know it.
7. For a change to an existing token (remove or replace): the first 8 characters of that token. Never paste a full token into the case.

What happens next

1. Support checks the request and schedules the change for your community's regional maintenance window. Support confirms the date in your case.
2. The change is applied during that window. It takes effect within seconds and causes no downtime for your community.
3. Support confirms completion in your case. If a token was issued, the case contains a one-time link to it and names the header to send.

Receiving and using your token

• The link opens exactly once and expires 7 days after it was created. Open it yourself, on the machine where you will store the token, and copy the token straight into your secrets manager. Do not forward the link, and do not open it "just to check": the first open destroys it.
• If the page reports that the secret was not found, the link has either expired or already been opened by someone else. Tell Support in the case. A used link cannot be re-sent; Support will replace the token and send a new link.
• The token is a 64-character string. Send it as a request header on every request from that tool:
  • API access: x-khoros-api-access: <token>
  • Page access: x-khoros-bot-bypass: <token>
• Note the first 8 characters of the token. That prefix is how you and Support refer to the token later, without exposing it.
• Treat the token like a password. Use it server-side only. Never place it in browser JavaScript, mobile apps, public repositories, chat messages or support cases. If it is exposed, ask Support to replace it immediately.
• For an IP-based exception there is nothing to configure on your side.

Changing or removing an exception

Open a support case naming the community and the kind of access, and state what you need:

• Replace a token (for example after an exposure, or a staff change on your side): give the first 8 characters. You receive a new token through a one-time link. The old token stops working the moment the change is applied, so be ready to update your tool during the maintenance window.
• Remove a token you no longer use: give the first 8 characters.
• Add or remove addresses on an IP list: list them.

One community and one kind of access per request. A change to both production and staging, or to both page and API access, is two requests.

Troubleshooting

Symptom	Likely cause	What to do
Still 403 with a verification page after adding the token	The header is missing on some requests, has the wrong name, or the token was issued for a different community or environment	Check that every request from the tool carries the exact header named in your case, against the community and environment the exception was granted for
API token works on API calls but pages are still challenged	Expected. API access covers API paths only	Ask for page access if the tool also loads pages
403 with an error page, not a verification page	A firewall rule, or a block unrelated to CommunityGuard	Send Support the sample request; do not assume the exception failed
HTTP 429	A rate limit, which exceptions do not change	Open a case describing the volume; see What the exception does not change
One-time link says the secret was not found	Expired, or already opened	Tell Support; the token will be replaced
Token committed to a repository or shared in chat	Exposure	Ask Support to replace it, with the first 8 characters