Skip to main content

Version: 3.9.0

Key Authentication

An API gateway's primary role is to connect API consumers and providers. For security reasons, it should authenticate and authorize consumers before access to internal resources.

Key Authentication

APISIX has a flexible plugin extension system and a number of existing plugins for user authentication and authorization. For example:

In this tutorial, you will create a consumer with key authentication, and learn how to enable and disable key authentication.

Key Concepts


A consumer is an application or a developer who consumes the API.

In APISIX, a consumer requires a unique username to be created. As part of the key authentication configuration, you would also add one of the authentication plugins from the list above to the consumer's plugin field.

Key Authentication

Key authentication is a relatively simple but widely used authentication approach. The idea is as follows:

  1. Administrator adds an authentication plugin to the route.
  2. API consumers attach the key to the query string or headers for authentication when sending requests.


  1. Complete Get APISIX to install APISIX on Docker or Kubernetes.
  2. Complete Configure Routes.

Start a Sample Upstream Service

If you are running APISIX in Kubernetes, you will be deploying an httpbin application to your cluster in this section. Otherwise, skip to the next section where you will be using the hosted httpbin application as the upstream.

Start a sample httpbin application:

kubectl run httpbin --image kennethreitz/httpbin --port 80

You should see a pod/httpbin created response.

Expose the application's port 80 through a service:

kubectl expose pod httpbin --port 80

You should see a service/httpbin exposed response.

Configure Key Authentication

Create a Consumer

Create a consumer named tom and enable the key-auth plugin with an API key secret-key. All requests sent with the key secret-key should be authenticated as tom.


Please use a complex key in the production environment.

curl -i "" -X PUT -d '
"username": "tom",
"plugins": {
"key-auth": {
"key": "secret-key"

You will receive an HTTP/1.1 201 Created response if the consumer was created successfully.

Enable Authentication

Update the getting-started-ip route from Configure Routes to add the key-auth plugin:

curl -i "" -X PATCH -d '
"plugins": {
"key-auth": {}

You will receive an HTTP/1.1 200 OK response if the plugin was added successfully.


You will be verifying if the key authentication is successfully enabled in this section.

Send a Request without Any Key

Send a request without the apikey header.

curl -i ""

Since the key is not provided, you will receive an unauthorized HTTP/1.1 401 Unauthorized response.

Send a Request with a Wrong Key

Send a request with a wrong key in the apikey header.

curl -i "" -H 'apikey: wrong-key'

Since the key is incorrect, you will receive an HTTP/1.1 401 Unauthorized response.

Send a Request with the Correct Key

Send a request with the correct key in the apikey header.

curl -i "" -H 'apikey: secret-key'

Since the correct key is provided, you will receive an HTTP/1.1 200 OK response.

Disable Authentication

Disable the key authentication plugin by setting the _meta.disable parameter to true.

curl "" -X PATCH -d '
"plugins": {
"key-auth": {
"_meta": {
"disable": true

Send a request without any key to verify:

curl -i ""

Since key authentication is disabled, you will receive an HTTP/1.1 200 OK response.

What's Next

You have learned how to configure key authentication for a route. In the next tutorial, you will learn how to configure rate limiting. Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.


API7 Cloud

SOC2 Type IRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation