Configure Basic Authentication

Basic authentication is a common method for securing web services. It uses the standard HTTP Authorization header with a Basic scheme, followed by a base64-encoded string of username:password.

API7 Gateway provides the basic-auth plugin to handle this authentication flow and validate credentials against its consumer credential database.

Use this guide for the standard setup workflow. For the full plugin field reference and advanced behaviors, see basic-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 Basic Authentication

Setting up basic authentication involves three steps:

1. Create a published service with a valid upstream.
2. Create a route that enables basic-auth.
3. Create a consumer and attach a basic auth credential.

Step 1: Create a Published Service with an Upstream

Admin API

curl -k "https://localhost:7443/apisix/admin/services/basic-auth-httpbin-service?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "basic-auth-httpbin-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

ADC

adc.yaml

services:
  - name: basic-auth-httpbin-service
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: basic-auth-route
        uris:
          - /anything/basic-auth
        methods:
          - GET
        plugins:
          basic-auth:
            hide_credentials: true
consumers:
  - username: basic-auth-consumer
    credentials:
      - name: basic-auth-consumer-cred
        type: basic-auth
        config:
          username: alice
          password: secret-password

adc sync -f adc.yaml

Step 2: Create a Route and Enable basic-auth

Admin API

curl -k "https://localhost:7443/apisix/admin/routes/basic-auth-route?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "basic-auth-route",
    "paths": ["/anything/basic-auth"],
    "methods": ["GET"],
    "service_id": "basic-auth-httpbin-service",
    "plugins": {
      "basic-auth": {
        "hide_credentials": true
      }
    }
  }'

ADC

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

Step 3: Create a Consumer and Credential

Admin API

# 1. Create the consumer
curl -k "https://localhost:7443/apisix/admin/consumers/basic-auth-consumer?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "basic-auth-consumer"
  }'

# 2. Create the basic-auth credential
curl -k "https://localhost:7443/apisix/admin/consumers/basic-auth-consumer/credentials/basic-auth-consumer-cred?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "basic-auth-consumer-cred",
    "plugins": {
      "basic-auth": {
        "username": "alice",
        "password": "secret-password"
      }
    }
  }'

ADC

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

Validate the Configuration

Send a request without the Authorization header. The gateway should reject it with 401 Unauthorized:

curl -i "http://127.0.0.1:9080/anything/basic-auth"

Then send the request with the correct credentials:

curl -i "http://127.0.0.1:9080/anything/basic-auth" \
  -u alice:secret-password

You should receive 200 OK, and the upstream response should include headers similar to the following:

{
  "headers": {
    "X-Consumer-Username": "basic-auth-consumer",
    "X-Credential-Identifier": "basic-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 Key Authentication - secure your APIs using unique API keys.
• Configure JWT Authentication - use JSON Web Tokens for stateless authentication.
• Learn about Consumers and Credentials - understand how API7 Gateway manages API identities.