Skip to main content
Version: Next



The public-api is used for exposing an API endpoint through a general HTTP API router.

When you are using custom Plugins, you can use the public-api Plugin to define a fixed, public API for a particular functionality. For example, you can create a public API endpoint /apisix/plugin/jwt/sign for JWT authentication using the jwt-auth Plugin.

The public API added in a custom Plugin is not exposed by default and the user should manually configure a Route and enable the public-api Plugin on it.


uristringFalse""URI of the public API. When setting up a Route, use this attribute to configure the original public API URI.

Example usage#

The example below uses the jwt-auth Plugin and the key-auth Plugin along with the public-api Plugin. Refer to their documentation for it configuration. This step is omitted below and only explains the configuration of the public-api Plugin.

Basic usage#

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

curl -X PUT '' \    -H 'X-API-KEY: <api-key>' \    -H 'Content-Type: application/json' \    -d '{    "uri": "/apisix/plugin/jwt/sign",    "plugins": {        "public-api": {}    }}'

Now, if you make a request to the configured URI, you will receive a JWT response:

curl ''

Using custom URI#

You can also use a custom URI for exposing the API as shown below:

curl -X PUT '' \    -H 'X-API-KEY: <api-key>' \    -H 'Content-Type: application/json' \    -d '{    "uri": "/gen_token",    "plugins": {        "public-api": {            "uri": "/apisix/plugin/jwt/sign"        }    }}'

Now you can make requests to this new endpoint:

curl ''

Securing the Route#

You can use the key-auth Plugin to add authentication and secure the Route:

curl -X PUT '' \    -H 'X-API-KEY: <api-key>' \    -H 'Content-Type: application/json' \    -d '{    "uri": "/gen_token",    "plugins": {        "public-api": {            "uri": "/apisix/plugin/jwt/sign"        },        "key-auth": {}    }}'

Now, only authenticated requests are allowed:

curl -i ''    -H "apikey: test-apikey"
HTTP/1.1 200 OK

The below request will fail:

curl -i ''

Disable Plugin#

To disable the public-api 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": "/hello",  "upstream": {    "type": "roundrobin",    "nodes": {      "": 1    }  }}'