Access Control Lists (ACLs)

Access Control Lists (ACLs) restrict API access using the consumer-restriction plugin. The plugin can match on consumer name, consumer group ID, service ID, or route ID, and supports both whitelists and blacklists. The example below uses consumer-name matching, which is the default and the most common pattern.

Capabilities

• Multiple identifier types: Match on consumer name (default), consumer group ID, service ID, or route ID via the plugin's type field.
• Whitelist and blacklist: Explicitly allow or deny traffic from the configured identifiers.
• Plugin integration: Combine with authentication plugins (e.g., key-auth, jwt-auth) so the gateway knows which consumer made the request.
• Granular control: Attach ACLs to a route, a service, or a consumer.

Prerequisites

1. Create a consumer (see Tutorial: Proxying and Managing API Requests via Plugins).
2. Add an authentication method (e.g., key-auth) to the consumer via a credential.
3. Have a service to attach the route to. The example below assumes a service named acl-service already exists; replace it with your own service.

Configure ACL

To restrict access to a route, configure the consumer-restriction plugin on the route alongside an authentication plugin.

Admin API

curl -k "https://localhost:7443/apisix/admin/routes/acl-restricted-route?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acl-restricted-route",
    "service_id": "acl-service",
    "paths": ["/restricted-api/*"],
    "plugins": {
      "key-auth": {},
      "consumer-restriction": {
        "whitelist": [
          "authorized-consumer"
        ]
      }
    }
  }'

Replace {group_id} with the gateway group ID from the Gateway Groups page in the Dashboard (use default for the gateway group created by the quickstart). Replace acl-service with the name of your service and authorized-consumer with the consumer username you want to allow.

ADC

adc.yaml

services:
  - name: acl-service
    upstream:
      scheme: http
      nodes:
        - host: your-upstream.example.com
          port: 80
          weight: 100
    routes:
      - name: acl-restricted-route
        uris:
          - /restricted-api/*
        plugins:
          key-auth: {}
          consumer-restriction:
            whitelist:
              - authorized-consumer

adc sync -f adc.yaml

Key Configuration Parameters

Field	Type	Description
type	string	What whitelist/blacklist entries refer to. One of consumer_name (default), consumer_group_id, service_id, route_id.
whitelist	array[string]	Identifiers that are allowed access. The accepted identifier kind is determined by type.
blacklist	array[string]	Identifiers that are denied access. The accepted identifier kind is determined by type.
rejected_code	integer	The HTTP status code to return when a request is rejected (default 403).
rejected_msg	string	The error message to return when a request is rejected.

For configuration patterns beyond consumer-name matching (such as restricting which consumers can access a given service or route, or restricting allowed HTTP methods per consumer), see the consumer-restriction plugin reference.

Implementation Patterns

Pattern 1: Whitelisting for Private Services

Use a whitelist to allow only specific internal consumers or partners to access private APIs. All other authenticated consumers will be rejected.

Pattern 2: Blacklisting Malicious Consumers

Use a blacklist to block specific consumers that have been identified as potentially malicious or are violating usage terms, while allowing all other authenticated consumers.

Next Steps

• Learn about RBAC for more complex permission models.
• Configure IP Restrictions to add another layer of security at the network level.