Project: APISIX (Orchestration & Management / API Gateway)
File: public-api.md

title: public-api keywords: Apache APISIX API Gateway Public API description: The public-api is used for exposing an API endpoint through a general HTTP API router. <!-- --> 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 Plugin. :::note 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. ::: | Name | Type | Required | Default | Description | ||--|-||--| | uri | string | False | "" | URI of the public API. When setting up a Route, use this attribute to configure the original public API URI. | The example below uses the Plugin and the 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. You can enable the Plugin on a specific Route as shown below: ```shell curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r1' \ -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: ```shell curl 'http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key' ``` You can also use a custom URI for exposing the API as shown below: ```shell curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r2' \ -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: ```shell curl 'http://127.0.0.1:9080/gen_token?key=user-key' ``` You can use the `key-auth` Plugin to add authentication and secure the Route: ```shell curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r2' \ -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: ```shell curl -i 'http://127.0.0.1:9080/gen_token?key=user-key' \ -H "apikey: test-apikey" ``` ```shell HTTP/1.1 200 OK ``` The below request will fail: ```shell curl -i 'http://127.0.0.1:9080/gen_token?key=user-key' ``` ```shell HTTP/1.1 401 Unauthorized ``` To remove 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. :::note You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```bash adminkey=$(yq '.deployment.admin.adminkey[0].key' conf/config.yaml | sed 's/"//g') ``` ::: ```shell curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' { "uri": "/hello", "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } } }' ```