key-auth

The key-auth plugin supports the use of an authentication key as a mechanism for clients to authenticate themselves before accessing upstream resources.

To use the plugin, you would configure authentication keys on consumers and enable the plugin on routes or services. The key can be included in the request URL query string or request header. APISIX will then verify the key to determine if a request should be allowed or denied to access upstream resources.

Examples​

The examples below demonstrate how you can work with the key-auth plugin for different scenarios.

Implement Key Authentication on Route​

The following example demonstrates how to implement key authentications on a route and include the key in the request header.

Create a consumer with key-auth and configure a key:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jack",
    "plugins": {
      "key-auth": {
        "key": "jack-key"
      }
    }
  }'

Create a route with key-auth:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "key-auth-route",
    "methods": ["GET"],
    "uri": "/anything",
    "plugins": {
      "key-auth": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Verify with a Valid Key​

Send a request to with the valid key:

curl -i "http://127.0.0.1:9080/anything" -H 'apikey: jack-key'

You should receive an HTTP/1.1 200 OK response.

Verify with an Invalid Key​

Send a request with an invalid key:

curl -i "http://127.0.0.1:9080/anything" -H 'apikey: wrong-key'

You should see an HTTP/1.1 401 Unauthorized response with the following:

{"message":"Invalid API key in request"}

Verify without a Key​

Send a request to without a key:

curl -i "http://127.0.0.1:9080/anything"

You should see an HTTP/1.1 401 Unauthorized response with the following:

{"message":"Missing API key found in request"}

Hide Authentication Information From Upstream​

The following example demonstrates how to prevent the key from being sent to the upstream services by configuring hide_credentials. By default, the authentication key is forwarded to the upstream services, which might lead to security risks in some circumstances.

Create a consumer with key-auth and configure a key:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "username": "jack",
  "plugins": {
    "key-auth": {
      "key": "jack-key"
    }
  }
}'

Without Hiding Credentials​

Create a route with key-auth and configure hide_credentials to false, which is the default configuration:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "id": "key-auth-route",
  "methods": ["GET"],
  "uri": "/anything",
  "plugins": {
    "key-auth": {
      "hide_credentials": false
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

Send a request with the valid key:

curl -i "http://127.0.0.1:9080/anything?apikey=jack-key"

You should see an HTTP/1.1 200 OK response with the following:

{
  "args": {
    "auth": "jack-key"
  },
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.2.1",
    "X-Amzn-Trace-Id": "Root=1-6502d8a5-2194962a67aa21dd33f94bb2",
    "X-Forwarded-Host": "127.0.0.1"
  },
  "json": null,
  "method": "GET",
  "origin": "127.0.0.1, 103.248.35.179",
  "url": "http://127.0.0.1/anything?apikey=jack-key"
}

Note that the credential jack-key is visible to the upstream service.

Hide Credentials​

Update the plugin's hide_credentials to true:

curl "http://127.0.0.1:9180/apisix/admin/routes/key-auth-route" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "plugins": {
    "key-auth": {
      "hide_credentials": true
    }
  }
}'

Send a request with the valid key:

curl -i "http://127.0.0.1:9080/anything?apikey=jack-key"

You should see an HTTP/1.1 200 OK response with the following:

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.2.1",
    "X-Amzn-Trace-Id": "Root=1-6502d85c-16f34dbb5629a5960183e803",
    "X-Forwarded-Host": "127.0.0.1"
  },
  "json": null,
  "method": "GET",
  "origin": "127.0.0.1, 103.248.35.179",
  "url": "http://127.0.0.1/anything"
}

Note that the credential jack-key is no longer visible to the upstream service.

Demonstrate Priority of Keys in Header and Query​

The following example demonstrates how to implement key authentication by consumers on a route and customize the URL parameter that should include the key. The example also shows that when the API key is configured in both the header and the query string, the request header has a higher priority.

Create a consumer with key-auth and configure a key:

curl 'http://127.0.0.1:9180/apisix/admin/consumers' -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "username": "jack",
  "plugins": {
    "key-auth": {
      "key": "jack-key"
    }
  }
}'

Create a route with key-auth:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "id": "key-auth-route",
  "methods": ["GET"],
  "uri": "/anything",
  "plugins": {
    "key-auth": {
      "query": "auth"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

Verify with a Valid Key​

Send a request to with the valid key:

curl -i "http://127.0.0.1:9080/anything?auth=jack-key"

You should receive an HTTP/1.1 200 OK response.

Verify with an Invalid Key​

Send a request with an invalid key:

curl -i "http://127.0.0.1:9080/anything?auth=wrong-key"

You should see an HTTP/1.1 401 Unauthorized response with the following:

{"message":"Invalid API key in request"}

Verify with a Valid Key in Query String​

However, if you include the valid key in header with the invalid key still in the URL query string:

curl -i "http://127.0.0.1:9080/anything?auth=wrong-key" -H 'apikey: jack-key'

You should see an HTTP/1.1 200 OK response. This shows that the key included in the header always has a higher priority.