---
description: Block or challenge requests based on User-Agent header values.
title: User Agent Blocking
image: https://developers.cloudflare.com/og-docs.png
---

[Skip to content](#main-content)

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

# User Agent Blocking

Last updated Aug 27, 2026|Copy as Markdown|[View as Markdown](https://41dd6664.previews.developers.cloudflare.com/waf/tools/user-agent-blocking/index.md)|[Agent setup](https://41dd6664.previews.developers.cloudflare.com/agent-setup/)

User Agent Blocking allows you to block specific browser or web application [User-Agent request headers ↗](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/User-Agent). User agent rules apply to the entire domain instead of individual subdomains.

User agent rules are applied after [zone lockdown rules](https://41dd6664.previews.developers.cloudflare.com/waf/tools/zone-lockdown/). If you allow an IP address via Zone Lockdown, it will skip any user agent rules.

Note

Cloudflare recommends that you use [custom rules](https://41dd6664.previews.developers.cloudflare.com/waf/custom-rules/) instead of user agent rules to block specific user agents.

For example, a custom rule equivalent to the user agent [example rule](#create-a-user-agent-blocking-rule) provided in this page could have the following configuration:

* **Expression**: `http.user_agent eq "BadBot/1.0.2 (+http://bad.bot)"`
* **Action**: (a block or challenge action)

## Availability

Cloudflare User Agent Blocking is available on all plans. The **User agent rules** option appears only if you have configured at least one user agent rule.

The number of available user agent rules depends on your Cloudflare plan.

|                 | Free | Pro | Business | Enterprise |
| --------------- | ---- | --- | -------- | ---------- |
| Availability    | Yes  | Yes | Yes      | Yes        |
| Number of rules | 10   | 50  | 250      | 1,000      |

## Create a User Agent Blocking rule

Note

The **User agent rules** option appears only if you have configured at least one user agent rule. Cloudflare recommends that you use [custom rules](https://41dd6664.previews.developers.cloudflare.com/waf/custom-rules/) instead of user agent rules.

1. In the Cloudflare dashboard, go to the **Security rules** page.  
[Go to **Security rules** ↗](https://dash.cloudflare.com/?to=/:account/:zone/security/security-rules)
2. Select **Create rule** \> **User agent rules**.
3. Enter a descriptive name for the rule in **Name/Description**.
4. In **Action**, select the action to perform: _Block_, _Non-Interactive Challenge_, _Managed Challenge_, or _Interactive Challenge_.
5. Enter a user agent value in **User Agent** (wildcards such as `*` are not supported). For example, to block the Bad Bot web spider, enter `BadBot/1.0.2 (+http://bad.bot)`.
6. Select **Save and Deploy blocking rule**.

Issue a `POST` request for the [Create a User Agent Blocking rule](https://41dd6664.previews.developers.cloudflare.com/api/resources/firewall/subresources/ua%5Frules/methods/create/) operation similar to the following:

Required API token permissions

At least one of the following [token permissions](https://41dd6664.previews.developers.cloudflare.com/fundamentals/api/reference/permissions/) is required:
* `Firewall Services Write`

```bash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/firewall/ua_rules" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"description": "Block Bad Bot web spider",
		"mode": "block",
		"configuration": {
				"target": "ua",
				"value": "BadBot/1.0.2 (+http://bad.bot)"
		}
	}'
```

## Challenge actions

When a User Agent Blocking rule uses a challenge action such as _Managed Challenge_, the visitor must pass a challenge page. After passing the challenge, a `cf_clearance` cookie is set. The duration of this cookie is controlled by the [Challenge Passage](https://41dd6664.previews.developers.cloudflare.com/cloudflare-challenges/challenge-types/challenge-pages/challenge-passage/) setting.

## Related resources

* [Secure your application](https://41dd6664.previews.developers.cloudflare.com/learning-paths/application-security/account-security/)
* [Cloudflare Zone Lockdown](https://41dd6664.previews.developers.cloudflare.com/waf/tools/zone-lockdown/)

Was this helpful?

YesNo

## On this page

[![](https://41dd6664.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://41dd6664.previews.developers.cloudflare.com/)

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/waf/tools/user-agent-blocking/#page","headline":"User Agent Blocking · Cloudflare Web Application Firewall (WAF) docs","description":"Block or challenge requests based on User-Agent header values.","url":"https://developers.cloudflare.com/waf/tools/user-agent-blocking/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-27","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}
```