Project: APISIX (Orchestration & Management / API Gateway)
File: key-authentication.md

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 . 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. 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. Key authentication is a relatively simple but widely used authentication approach. The idea is as follows: Administrator adds an authentication key (API key) to the Route. API consumers add the key to the query string or headers for authentication when sending requests. Complete to install APISIX. Complete . 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 Created` response if the consumer was created successfully. Inheriting the route `getting-started-ip` from , 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. Let's validate the authentication in the following scenarios: 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 ``` 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 ``` 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 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. You have learned how to configure key authentication for a route. In the next tutorial, you will learn how to configure rate limiting.