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

Prerequisites

• An API7 Enterprise instance is running.
• A Gateway Group is created and a Gateway instance is running.
• A token from the Dashboard.

Configure Key Authentication

Setting up key authentication involves three steps:

1. Create a published 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 Published Service with an Upstream

Create a published service that proxies requests to httpbin.org.

Admin API

curl -k "https://localhost:7443/apisix/admin/services/key-auth-httpbin-service?gateway_group_id={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

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
consumers:
  - username: key-auth-consumer
    credentials:
      - name: key-auth-consumer-cred
        type: key-auth
        config:
          key: secret-api-key

adc sync -f adc.yaml

Step 2: Create a Route and Enable key-auth

Create a route that points to the service and requires an apikey header.

Admin API

curl -k "https://localhost:7443/apisix/admin/routes/key-auth-route?gateway_group_id={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"
      }
    }
  }'

ADC

The route is already included in the previous adc.yaml example.

Step 3: Create a Consumer and Credential

Create a consumer that represents the client, then attach a key-auth credential.

Admin API

# 1. Create the consumer
curl -k "https://localhost:7443/apisix/admin/consumers/key-auth-consumer?gateway_group_id={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={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"
      }
    }
  }'

ADC

The consumer and credential are already included in the previous adc.yaml example.

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

• Configure Basic Authentication - use standard username and password credentials.
• Configure JWT Authentication - use JSON Web Tokens for stateless authentication.
• Learn about Consumers and Credentials - understand how API7 Gateway manages API identities.