Skip to main content
APIContext
Talk to salesStart free
Start HereGuidesConceptsCLIReferenceChangelogStatus

Identify and allow-list APIContext monitor traffic

A web application firewall (WAF) or bot manager can block a monitor request because it looks automated. To allow monitor traffic without opening your API to everyone, your security team needs to know what an APIContext monitor sends and which of those signals are safe to match on. This page covers API monitors. It does not cover Browser or MCP monitors.

What an API monitor sends​

Three things identify a request from an API monitor: the user agent, the traceparent header, and the address it comes from.

User agent. The User-Agent value begins with APImetrics/, followed by the platform version, then the PycURL and libcurl versions, then the versions of other libraries, for example APImetrics/<version> PycURL/<version> libcurl/<version> OpenSSL/<version>. The version numbers change as the platform is updated, so match on the APImetrics/ prefix and never on a full string.

The traceparent header. Each run sends a traceparent header in the W3C Trace Context format, 00-<trace-id>-<parent-id>-01. The trace ID is 32 hexadecimal characters and the parent ID is 16, and by default both are generated at random for each run. HTTP header names are case-insensitive, so your gateway may log it as Traceparent.

The value is recorded with the result and returned as otel_traceparent_id in performance results webhooks. Use it to find the exact request in your own server or CDN logs, as in Akamai DataStream 2 logs. Because it is different every run, it cannot be used to allow traffic.

Source addresses. Public nodes call your API from published IP addresses. Node locations and IP addresses lists every address by region and cloud, and publishes DNS names that resolve to them, such as all.agents.apimetrics.io for every region. Use the DNS names where your firewall supports them, because the addresses change over time and that page keeps a changelog.

Why the user agent alone is not enough​

The user agent is a plain text header that any client can send, so a rule that allows anything starting with APImetrics/ also allows anyone who copies the string. A rule on addresses alone is stronger but is only as current as your copy of the list. For a rule that stays tight, match on a value that only your team and your monitors know, and combine it with the source addresses.

Add your own header to a monitor​

An API monitor's Advanced tab has a Use APIContext Standard Headers setting, which the screen describes as "standard headers that identify APIContext calls." This page does not list those headers yet. To match on a value that you control, add your own header: a monitor can send any header you give it. Pick a header name that your own systems do not use and a long random value, add both to the monitor, and write your WAF or bot manager rule to require the header and its exact value.

In the monitor editor, the header goes in the Headers section of the request. Through the API, it is an entry in the monitor's headers array, which holds key and value pairs. This request body adds one header to an API monitor with create an API monitor, and the same headers array is accepted by patch an API monitor for an existing monitor:

{
  "name": "Check payments API",
  "method": "GET",
  "url": "https://api.example.com/v1/health",
  "headers": [
    { "key": "Accept", "value": "application/json" },
    { "key": "X-Synthetic-Monitor", "value": "<long-random-value>" }
  ]
}

X-Synthetic-Monitor is an example name chosen for this page. APIContext does not add it.

The header is part of the monitor definition, so anyone who can view the monitor can read the value, and the request recorded with each result includes it. Treat it as an identifying token, not as a credential, and change it on the monitor and in your rule together if it is exposed. Each vendor documents how to build a rule that matches a request header, so follow your WAF or bot manager documentation for that side.

Next steps​