# Configure Key Authentication Key authentication is one of the simplest ways to secure an API. Each client is assigned a unique API key, which they must include in their requests. API7 Gateway validates the key against its consumer credential database before allowing the request to proceed to the upstream service. The [`key-auth`](https://docs.api7.ai/hub/key-auth.md) plugin implements this pattern and supports looking for the key in both headers and query parameters. Use this guide for the standard setup workflow. For the full plugin field reference and advanced behaviors such as anonymous consumers and credential forwarding, see [`key-auth`](https://docs.api7.ai/hub/key-auth.md). ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") * An API7 Enterprise instance is running. * A Gateway Group is created and a Gateway instance is running. * A [token from the Dashboard](https://docs.api7.ai/api7-gateway/reference/obtain-dashboard-token.md). ## Configure Key Authentication[​](#configure-key-authentication "Direct link to Configure Key Authentication") Setting up key authentication involves three steps: 1. Create a service with a valid upstream. 2. Create a route that enables `key-auth`. 3. Create a consumer and attach a key credential. ### Step 1: Create a Service with an Upstream[​](#step-1-create-a-service-with-an-upstream "Direct link to Step 1: Create a Service with an Upstream") Create a service that proxies requests to `httpbin.org`. * Admin API * ADC ``` curl -k "https://localhost:7443/apisix/admin/services/key-auth-httpbin-service?gateway_group_id={gateway_group_id}" -X PUT \ -H "X-API-KEY: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "name": "key-auth-httpbin-service", "upstream": { "type": "roundrobin", "scheme": "http", "nodes": [ { "host": "httpbin.org", "port": 80, "weight": 100 } ] } }' ``` adc.yaml ``` services: - name: key-auth-httpbin-service upstream: name: default scheme: http nodes: - host: httpbin.org port: 80 weight: 100 routes: - name: key-auth-route uris: - /anything/key-auth methods: - GET plugins: key-auth: header: apikey labels: docs-example: key-auth-httpbin-service consumers: - username: key-auth-consumer credentials: - name: key-auth-consumer-cred type: key-auth config: key: secret-api-key labels: docs-example: key-auth-httpbin-service ``` Preview the changes owned by this example and confirm that the diff contains no unintended updates or deletions: ``` adc diff -f adc.yaml \ --include-resource-type service \ --include-resource-type consumer \ --label-selector docs-example=key-auth-httpbin-service ``` Synchronize the reviewed configuration: ``` adc sync -f adc.yaml \ --include-resource-type service \ --include-resource-type consumer \ --label-selector docs-example=key-auth-httpbin-service ``` ### Step 2: Create a Route and Enable `key-auth`[​](#step-2-create-a-route-and-enable-key-auth "Direct link to step-2-create-a-route-and-enable-key-auth") Create a route that points to the service and requires an `apikey` header. * Admin API * ADC ``` curl -k "https://localhost:7443/apisix/admin/routes/key-auth-route?gateway_group_id={gateway_group_id}" -X PUT \ -H "X-API-KEY: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "name": "key-auth-route", "paths": ["/anything/key-auth"], "methods": ["GET"], "service_id": "key-auth-httpbin-service", "plugins": { "key-auth": { "header": "apikey" } } }' ``` The route is already included in the previous `adc.yaml` example. ### Step 3: Create a Consumer and Credential[​](#step-3-create-a-consumer-and-credential "Direct link to Step 3: Create a Consumer and Credential") Create a consumer that represents the client, then attach a `key-auth` credential. * Admin API * ADC ``` # 1. Create the consumer curl -k "https://localhost:7443/apisix/admin/consumers/key-auth-consumer?gateway_group_id={gateway_group_id}" -X PUT \ -H "X-API-KEY: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "username": "key-auth-consumer" }' # 2. Create the key-auth credential curl -k "https://localhost:7443/apisix/admin/consumers/key-auth-consumer/credentials/key-auth-consumer-cred?gateway_group_id={gateway_group_id}" -X PUT \ -H "X-API-KEY: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "name": "key-auth-consumer-cred", "plugins": { "key-auth": { "key": "secret-api-key" } } }' ``` The consumer and credential are already included in the previous `adc.yaml` example. ## Validate the Configuration[​](#validate-the-configuration "Direct link to Validate the Configuration") Send a request without the API key. The gateway should reject it with `401 Unauthorized`: ``` curl -i "http://127.0.0.1:9080/anything/key-auth" ``` Then send the request with the correct API key: ``` curl -i "http://127.0.0.1:9080/anything/key-auth" \ -H "apikey: secret-api-key" ``` You should receive `200 OK`, and the upstream response should include headers similar to the following: ``` { "headers": { "Apikey": "secret-api-key", "X-Consumer-Username": "key-auth-consumer", "X-Credential-Identifier": "key-auth-consumer-cred" } } ``` If the authenticated request still returns `401`, or the route returns `404`, immediately after you apply the configuration, wait a few seconds for the latest configuration to reach the gateway and retry. ## Next Steps[​](#next-steps "Direct link to Next Steps") * [Configure Basic Authentication](https://docs.api7.ai/api7-gateway/how-to-guides/api-security/basic-auth.md) - use standard username and password credentials. * [Configure JWT Authentication](https://docs.api7.ai/api7-gateway/how-to-guides/api-security/jwt-auth.md) - use JSON Web Tokens for stateless authentication. * [Learn about Consumers and Credentials](https://docs.api7.ai/api7-gateway/key-concepts/consumers-and-credentials.md) - understand how API7 Gateway manages API identities.