How to use the user_agent parameter to prevent firewall blocking for API2Cart integrations

For open-source platforms (such as Magento, WooCommerce, PrestaShop, etc., connected via either bridge or native API), issues often arise due to connection blocking on the store's firewall. Clients frequently encounter situations where the firewall blocks legitimate requests from API2Cart, considering them potentially harmful. This can disrupt integrations and lead to an increase in support requests.

To prevent such issues on these platforms, we recommend using the user_agent parameter, which allows for clear identification of requests made through API2Cart. Unlike IP addresses, which can change or may not be unique, user_agent enables the creation of a persistent identifier for each connection. As a result, if the firewall supports configuring rules for User-Agent, you can predefine rules to allow requests from API2Cart without blocking them.

The user_agent parameter is supported in the account.cart.add and account.config.update methods, as well as when adding or editing a store in the UI under the additional parameters section.

If this parameter is set, API2Cart will send requests to the store with the User-Agent header.

Use a unique user_agent value for each store

Do not set the same user_agent value for all the stores you connect. Instead, generate a separate value for each store and pass it only to that store's owner, who adds it to their firewall rule. This way, the value is known only to you and to the store owner.

This adds an extra layer of protection. A firewall rule that lets requests through by User-Agent works for anyone who sends that header. If a single shared value becomes known — for example, from server logs, a support ticket or a screenshot — it can be used to bypass the firewall of every store that trusts it. With a unique value per store, a leaked value affects only one store and can be replaced without touching the others.

• Make it random — use at least 16 random characters that are not derived from the store URL, name or ID. A recognizable prefix is fine, for example API2Cart-Integration/7f3kQ9xL2mB8vR4t.
• Keep it private — send it to the store owner through a private channel and do not publish it in public documentation, forums or code repositories.
• Replace it if it leaks — generate a new value, set it with the account.config.update method or in the store's additional parameters in the UI, and ask the store owner to update the firewall rule at the same time. Until both match, requests to the store will be blocked.

Keep in mind that the User-Agent header is not a password: it is sent with every request and can appear in server logs. A unique value limits the damage if it leaks, but it does not replace other security measures.

Example: allowing API2Cart requests in Cloudflare

For example, Cloudflare lets you allow or block requests based on the User-Agent header with a custom WAF rule. Custom rules have no separate Allow action — to let requests through, use the Skip action.

To configure this rule, follow these steps:

• In the Cloudflare dashboard, select your domain and go to Security > Security rules. In the previous dashboard navigation, this is Security > WAF > Custom rules.
• Click Create rule and select Custom rules.
• Enter a rule name, for example Allow API2Cart.
• Under If incoming requests match..., set Field to User Agent, Operator to equals, and Value to the "user_agent" parameter value defined for this store in API2Cart. The value must match exactly, including letter case.
• Under Then take action..., choose Skip and select the security features that block API2Cart requests on your store, for example All managed rules, All Super Bot Fight Mode rules or All remaining custom rules. Skip only what is necessary. If you skip the remaining custom rules, place this rule first in the list.
• Apply the rule by clicking Deploy.

If the firewall does not support filtering by User-Agent, the only solution is to whitelist API2Cart's IP addresses.