Skip to main content
Version: 3.3

Key Authentication

The Getting Started tutorials are contributed by API7.ai.

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.

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.

What is a Consumer#

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

In APISIX, a Consumer requires a unique username and an authentication plugin from the list above to be created.

What is Key Authentication#

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

  1. Administrator adds an authentication key (API key) to the Route.
  2. API consumers add the key to the query string or headers for authentication when sending requests.

Enable Key Authentication#

Prerequisite(s)#

  1. Complete Get APISIX to install APISIX.
  2. Complete Configure Routes.

Create a Consumer#

Let's 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.

caution

Please use a complex key in the Production environment.

curl -i "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT -d '
{
  "username": "tom",
  "plugins": {
    "key-auth": {
      "key": "secret-key"
    }
  }
}'

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

Enable Authentication#

Inheriting the route getting-started-ip from Configure Routes, we only need to use the PATCH method to add the key-auth plugin to the route:

curl -i "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d '
{
  "plugins": {
    "key-auth": {}
  }
}'

You will receive an HTTP/1.1 201 Created response if the plugin was added successfully.

Validate#

Let's validate the authentication in the following scenarios:

1. Send a request without any key#

Send a request without the apikey header.

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

Since you enabled the key authentication, you will receive an unauthorized response with HTTP/1.1 401 Unauthorized.

HTTP/1.1 401 Unauthorized
Date: Wed, 08 Feb 2023 09:38:36 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/3.1.0

2. Send a request with a wrong key#

Send a request with a wrong key (e.g. wrong-key) in the apikey header.

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

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

HTTP/1.1 401 Unauthorized
Date: Wed, 08 Feb 2023 09:38:27 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/3.1.0

3. Send a request with the correct key#

Send a request with the correct key (secret-key) in the apikey header.

curl -i "http://127.0.0.1:9080/ip" -H 'apikey: secret-key'

You will receive an HTTP/1.1 200 OK response.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 44
Connection: keep-alive
Date: Thu, 09 Feb 2023 03:27:57 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Server: APISIX/3.1.0

Disable Authentication#

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

curl "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d '
{
  "plugins": {
    "key-auth": {
      "_meta": {
        "disable": true
      }
    }
  }
}'

You can send a request without any key to validate:

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

Because you have disabled the key authentication plugin, 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.