Skip to main content
Version: Next



The ua-restriction Plugin allows you to restrict access to a Route or Service based on the User-Agent header with an allowlist and a denylist.


NameTypeRequiredDefaultValid valuesDescription
bypass_missingbooleanFalsefalseWhen set to true, bypasses the check when the User-Agent header is missing.
allowlistarray[string]FalseList of allowed User-Agent headers.
denylistarray[string]FalseList of denied User-Agent headers.
messagestringFalseNot allowed.length range: [1, 1024]Message with the reason for denial to be added to the response.

Both allowlist and denylist can be used on their own. If they are used together, the allowlist matches before the denylist.

Enabling the Plugin#

You can enable the Plugin on a Route or a Service as shown below:

curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "uri": "/index.html",    "upstream": {        "type": "roundrobin",        "nodes": {            "": 1        }    },    "plugins": {        "ua-restriction": {             "bypass_missing": true,             "allowlist": [                 "my-bot1",                 "(Baiduspider)/(\\d+)\\.(\\d+)"             ],             "denylist": [                 "my-bot2",                 "(Twitterspider)/(\\d+)\\.(\\d+)"             ]        }    }}'

You can also configure the Plugin to respond with a custom rejection message:

"plugins": {    "ua-restriction": {        "denylist": [            "my-bot2",            "(Twitterspider)/(\\d+)\\.(\\d+)"        ],        "message": "Do you want to do something bad?"    }}

Example usage#

After you have configured the Plugin as shown above, you can make a normal request which will get accepted:

curl -i
HTTP/1.1 200 OK...

Now if the User-Agent header is in the denylist i.e the bot User-Agent:

curl --header 'User-Agent: Twitterspider/2.0'
HTTP/1.1 403 Forbidden

Disable Plugin#

To disable the ua-restriction Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "uri": "/index.html",    "plugins": {},    "upstream": {        "type": "roundrobin",        "nodes": {            "": 1        }    }}'