docs/en/latest/getting-started/key-authentication.md - apisix - Git at Google

 ---
 title: Key Authentication
 slug: /getting-started/key-authentication
 ---

 <head>
   <link rel="canonical" href="https://docs.api7.ai/apisix/getting-started/key-authentication" />
 </head>

 > The Getting Started tutorials are contributed by [API7.ai](https://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.

 ![Key Authentication](https://static.apiseven.com/uploads/2023/02/08/8mRaK3v1_consumer.png)

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

 - [Key Authentication](https://apisix.apache.org/docs/apisix/plugins/key-auth/)
 - [Basic Authentication](https://apisix.apache.org/docs/apisix/plugins/basic-auth/)
 - [JSON Web Token (JWT) Authentication](https://apisix.apache.org/docs/apisix/plugins/jwt-auth/)
 - [Keycloak](https://apisix.apache.org/docs/apisix/plugins/authz-keycloak/)
 - [Casdoor](https://apisix.apache.org/docs/apisix/plugins/authz-casdoor/)
 - [Wolf RBAC](https://apisix.apache.org/docs/apisix/plugins/wolf-rbac/)
 - [OpenID Connect](https://apisix.apache.org/docs/apisix/plugins/openid-connect/)
 - [Central Authentication Service (CAS)](https://apisix.apache.org/docs/apisix/plugins/cas-auth/)
 - [HMAC](https://apisix.apache.org/docs/apisix/plugins/hmac-auth/)
 - [Casbin](https://apisix.apache.org/docs/apisix/plugins/authz-casbin/)
 - [LDAP](https://apisix.apache.org/docs/apisix/plugins/ldap-auth/)
 - [Open Policy Agent (OPA)](https://apisix.apache.org/docs/apisix/plugins/opa/)
 - [Forward Authentication](https://apisix.apache.org/docs/apisix/plugins/forward-auth/)

 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](./README.md) to install APISIX.
 2. Complete [Configure Routes](./configure-routes.md#what-is-a-route).

 ### 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.

 :::

 ```shell
 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](./configure-routes.md), we only need to use the `PATCH` method to add the `key-auth` plugin to the route:

 ```shell
 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.

 ```shell
 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`.

 ```text
 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.

 ```shell
 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`.

 ```text
 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.

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

 You will receive an `HTTP/1.1 200 OK` response.

 ```text
 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`.

 ```shell
 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:

 ```shell
 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.
	---
	title: Key Authentication
	slug: /getting-started/key-authentication
	---

	<head>
	<link rel="canonical" href="https://docs.api7.ai/apisix/getting-started/key-authentication" />
	</head>

	> The Getting Started tutorials are contributed by [API7.ai](https://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.

	![Key Authentication](https://static.apiseven.com/uploads/2023/02/08/8mRaK3v1_consumer.png)

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

	- [Key Authentication](https://apisix.apache.org/docs/apisix/plugins/key-auth/)
	- [Basic Authentication](https://apisix.apache.org/docs/apisix/plugins/basic-auth/)
	- [JSON Web Token (JWT) Authentication](https://apisix.apache.org/docs/apisix/plugins/jwt-auth/)
	- [Keycloak](https://apisix.apache.org/docs/apisix/plugins/authz-keycloak/)
	- [Casdoor](https://apisix.apache.org/docs/apisix/plugins/authz-casdoor/)
	- [Wolf RBAC](https://apisix.apache.org/docs/apisix/plugins/wolf-rbac/)
	- [OpenID Connect](https://apisix.apache.org/docs/apisix/plugins/openid-connect/)
	- [Central Authentication Service (CAS)](https://apisix.apache.org/docs/apisix/plugins/cas-auth/)
	- [HMAC](https://apisix.apache.org/docs/apisix/plugins/hmac-auth/)
	- [Casbin](https://apisix.apache.org/docs/apisix/plugins/authz-casbin/)
	- [LDAP](https://apisix.apache.org/docs/apisix/plugins/ldap-auth/)
	- [Open Policy Agent (OPA)](https://apisix.apache.org/docs/apisix/plugins/opa/)
	- [Forward Authentication](https://apisix.apache.org/docs/apisix/plugins/forward-auth/)

	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](./README.md) to install APISIX.
	2. Complete [Configure Routes](./configure-routes.md#what-is-a-route).

	### 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.

	:::

	```shell
	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](./configure-routes.md), we only need to use the `PATCH` method to add the `key-auth` plugin to the route:

	```shell
	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.

	```shell
	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`.

	```text
	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.

	```shell
	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`.

	```text
	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.

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

	You will receive an `HTTP/1.1 200 OK` response.

	```text
	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`.

	```shell
	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:

	```shell
	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.