> ## Documentation Index
> Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Network access and allowlisting

> Allow Firmly traffic through merchant CDN, WAF, bot-management, and rate-limiting controls.

Configure allowlisting only when the merchant's CDN, WAF, bot-management system, or rate limiter blocks Firmly requests. Apply the selected method to every staging and production hostname that Firmly will access.

## Choose an allowlisting method

<CardGroup cols={3}>
  <Card title="Web Bot Auth" icon="signature">
    **Preferred where supported.** Verify Firmly's cryptographic HTTP message signatures without exchanging a shared secret.
  </Card>

  <Card title="Header-based" icon="key">
    **Broadly compatible.** Match a merchant-specific `x-agentic-auth` value while preserving the direct edge path.
  </Card>

  <Card title="IP-based" icon="network-wired">
    **Fallback only.** Match Firmly's fixed egress addresses when the security product cannot verify request identity.
  </Card>
</CardGroup>

| Method       | Use when                                                                          | Network path     | Identity                        |
| ------------ | --------------------------------------------------------------------------------- | ---------------- | ------------------------------- |
| Web Bot Auth | The merchant's edge supports Web Bot Auth or HTTP message-signature verification. | Distributed edge | Cryptographic signature         |
| Header-based | The security layer can match an exact request-header value.                       | Distributed edge | Merchant-specific shared secret |
| IP-based     | Neither request-level method can be supported.                                    | Fixed egress     | Source IP address               |

## Why request identity is preferred

Firmly runs on distributed edge infrastructure. Web Bot Auth and header-based allowlisting preserve that architecture because identity travels with each request to the merchant's CDN or WAF. IP allowlisting instead requires Firmly to route traffic through a limited set of fixed egress paths before it can reach the merchant.

```mermaid theme={null}
flowchart LR
    subgraph Identity["Request identity: distributed edge path"]
        HE["Firmly distributed edge"] -->|"Web Bot Auth signature or shared header"| HW["Merchant CDN / WAF"]
        HW --> HO["Merchant API"]
    end

    subgraph IP["IP-based: fixed egress path"]
        IE["Firmly distributed edge"] --> IG["Fixed egress gateway"]
        IG -->|"Allowlisted source IP"| IW["Merchant CDN / WAF"]
        IW --> IO["Merchant API"]
    end
```

Request-level identity:

* Preserves direct routing from Firmly's distributed edge to the merchant's edge.
* Identifies the request even when CDNs and reverse proxies obscure or replace source IP addresses.
* Avoids concentrating merchant traffic through fixed egress locations and the additional network path they require.
* Keeps access control independent of Firmly's network topology.

<Warning>
  IP allowlisting is a compatibility fallback, not an equivalent deployment model. It works against the distributed edge path by requiring traffic to exit through fixed network locations. If a CDN or reverse proxy replaces the source IP, it also cannot identify Firmly reliably. Use IP allowlisting only when the merchant cannot support Web Bot Auth or match `x-agentic-auth`.
</Warning>

## Web Bot Auth (preferred)

Firmly signs outbound requests using Web Bot Auth and publishes the corresponding public key directory. This lets the merchant verify Firmly cryptographically without relying on source IP addresses or a shared secret.

<Info>
  Cloudflare lists [FirmlyAI Bot](https://radar.cloudflare.com/bots/directory/firmlyai-bot) as a verified intermediary agent. Its registered Signature Agent URL is `https://api.firmly.online/.well-known/http-message-signatures-directory`.
</Info>

### Cloudflare-protected merchants

Cloudflare validates Firmly's Web Bot Auth signatures and recognizes matching requests as FirmlyAI Bot. Configure the merchant's bot and WAF policies to permit FirmlyAI Bot on the integration routes. Where the Cloudflare plan supports per-operator controls, use the FirmlyAI Bot entry or its BotBase detection ID rather than allowing all automated traffic.

See [Cloudflare's Web Bot Auth documentation](https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/) for verification behavior and plan-specific controls.

### Other edge providers

The edge provider or origin must support Web Bot Auth or RFC 9421 HTTP message-signature validation. It must retrieve Firmly's public key from the URL in `Signature-Agent` and validate `Signature-Input` and `Signature` before applying the allow policy.

<Steps>
  <Step title="Confirm support">
    Confirm that the merchant's CDN, WAF, API gateway, or origin can recognize FirmlyAI Bot or validate Web Bot Auth signatures.
  </Step>

  <Step title="Create the allow policy">
    Permit verified FirmlyAI Bot requests on the hostnames and routes required for the integration. Keep normal controls for requests that are unsigned or fail verification.
  </Step>

  <Step title="Preserve signature headers">
    Ensure proxies do not remove or rewrite `Signature-Agent`, `Signature-Input`, or `Signature` before validation occurs.
  </Step>

  <Step title="Confirm completion">
    Notify `ops@firmly.ai` that the policy is ready and identify the domain and environments. Firmly will enable signed requests and run verification.
  </Step>
</Steps>

## Header-based allowlisting

Firmly uses the `x-agentic-auth` request header with a unique shared-secret value for each merchant. Exchange the value through a secure channel; do not publish it in tickets, source code, or documentation.

<Steps>
  <Step title="Obtain the merchant-specific value">
    Coordinate with Firmly to generate and securely exchange the `x-agentic-auth` value for the merchant domain.
  </Step>

  <Step title="Create an exact-match rule">
    Match header name `x-agentic-auth` and the complete, case-sensitive secret value. Do not use a prefix, substring, or example value.
  </Step>

  <Step title="Allow the matching request">
    Configure the matching request to bypass the controls that would otherwise block Firmly, such as managed WAF rules, bot checks, and rate limits. Keep all normal controls for requests that do not match.
  </Step>

  <Step title="Prioritize and scope the rule">
    Evaluate the rule before blocking and rate-limiting rules. Scope it to the merchant hostnames and routes Firmly needs when the security product supports that restriction.
  </Step>

  <Step title="Confirm completion">
    Notify `ops@firmly.ai` that configuration is complete and identify the domain. Share the secret only through the agreed secure channel. Firmly will enable the same value on outbound requests and run verification.
  </Step>
</Steps>

<Note>
  For zero-downtime secret rotation, temporarily allow both the old and new values. Remove the old rule only after Firmly confirms that requests using the new value succeed.
</Note>

## IP allowlisting (fallback)

Use the following outbound addresses only when Web Bot Auth and header-based matching are unavailable. This method does not use request-level identity.

| IP address or CIDR       | Address family |
| ------------------------ | -------------- |
| `104.28.1.121/32`        | IPv4           |
| `24.199.70.88/32`        | IPv4           |
| `24.144.66.39/32`        | IPv4           |
| `161.35.254.19/32`       | IPv4           |
| `2a09:bac5:fff0:54::/64` | IPv6           |
| `2a09:bac6:fff0:54::/64` | IPv6           |

<Warning>
  IP allowlisting requires Firmly to route merchant traffic through fixed egress paths and can add latency to each request. Use Web Bot Auth or header-based allowlisting whenever either method is available.
</Warning>

<Steps>
  <Step title="Create the IP sets">
    Add all four IPv4 entries above. Add both IPv6 ranges when the security product and merchant endpoint support IPv6. Products that separate address families require distinct IPv4 and IPv6 sets.
  </Step>

  <Step title="Match the actual source address">
    Configure the rule at the network layer that receives Firmly's source address. If an upstream CDN replaces that address, use Web Bot Auth or header-based allowlisting instead of trusting an arbitrary forwarded-IP header.
  </Step>

  <Step title="Allow the matching request">
    Permit matching requests to bypass the blocking, bot-management, and rate-limiting controls required for the Firmly integration. Do not disable those controls globally.
  </Step>

  <Step title="Apply the rule to all integration hosts">
    Cover every staging and production hostname provided to Firmly. Confirm that the rule is evaluated before conflicting block rules.
  </Step>

  <Step title="Confirm completion">
    Send the domain, environments, and allowlisted ranges to `ops@firmly.ai`. Firmly will route verification traffic through the fixed egress path and confirm the result.
  </Step>
</Steps>

## Verification criteria

Firmly verifies the selected method before integration testing continues:

* Requests reach the expected merchant endpoint without a WAF block, bot challenge, or rate-limit response.
* Web Bot Auth rules recognize FirmlyAI Bot or validate its HTTP message signature; unsigned or invalid requests continue through the merchant's normal security policy.
* Header-based rules recognize only the complete merchant-specific value; requests without it continue through the merchant's normal security policy.
* IP-based rules recognize Firmly traffic through the fixed egress path.
* Catalog and cart validation can run without intermittent access failures.

When using IP allowlisting, always verify the IP list on this page before configuring a new environment or production cutover.