Skip to main content
Version: Next



The referer-restriction Plugin can be used to restrict access to a Service or a Route by whitelisting/blacklisting the Referer request header.


NameTypeRequiredDefaultValid valuesDescription
whitelistarray[string]FalseList of hostnames to whitelist. A hostname can start with * for wildcard.
blacklistarray[string]FalseList of hostnames to blacklist. A hostname can start with * for wildcard.
messagestringFalseYour referer host is not allowed[1, 1024]Message returned when access is not allowed.
bypass_missingbooleanFalsefalseWhen set to true, bypasses the check when the Referer request header is missing or malformed.

Only one of whitelist or blacklist attribute must be specified. They cannot work together.

Enabling the Plugin#

You can enable the Plugin on a specific 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": {        "referer-restriction": {            "bypass_missing": true,            "whitelist": [                "",                "*"            ]        }    }}'

Example usage#

Once you have configured the Plugin as shown above, you can test it by setting Referer:

curl -H 'Referer:'
HTTP/1.1 200 OK...

Now, if you make a request with Referer:, the request will be blocked:

curl -H 'Referer:'
HTTP/1.1 403 Forbidden...{"message":"Your referer host is not allowed"}

Since we have set bypass_missing to true a request without the Referer header will be successful as the check is skipped:

HTTP/1.1 200 OK...

Disable Plugin#

To disable the referer-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        }    }}'