Skip to main content
Version: 2.4




basic-auth is an authentication plugin that need to work with consumer. Add Basic Authentication to a service or route.

The consumer then adds its key to the request header to verify its request.

For more information on Basic authentication, refer to Wiki for more information.


usernamestringrequiredDifferent consumer should have different value which is unique. When different consumer use a same username, a request matching exception would be raised.
passwordstringrequiredthe user's password

How To Enable#

1. set a consumer and config the value of the basic-auth option#

curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "username": "foo",    "plugins": {        "basic-auth": {            "username": "foo",            "password": "bar"        }    }}'

you can visit Dashboard and add a Consumer through the web console:


then add basic-auth plugin in the Consumer page:


2. add a Route or add a Service, and enable the basic-auth plugin#

curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "methods": ["GET"],    "uri": "/hello",    "plugins": {        "basic-auth": {}    },    "upstream": {        "type": "roundrobin",        "nodes": {            "": 1        }    }}'

Test Plugin#

  • missing Authorization header
$ curl -i 401 Unauthorized...{"message":"Missing authorization in request"}
  • user is not exists:
$ curl -i -ubar:bar 401 Unauthorized...{"message":"Invalid user key in authorization"}
  • password is invalid:
$ curl -i -ufoo:foo 401 Unauthorized...{"message":"Password is error"}
  • success:
$ curl -i -ufoo:bar 200 OK...hello, world

Disable Plugin#

When you want to disable the basic-auth plugin, it is very simple, you can delete the corresponding json configuration in the plugin configuration, no need to restart the service, it will take effect immediately:

$ curl -X PUT -d value='{    "methods": ["GET"],    "uri": "/hello",    "plugins": {},    "upstream": {        "type": "roundrobin",        "nodes": {            "": 1        }    }}'