# Access Control Lists

Access control lists restrict API access using the `consumer-restriction` plugin. The plugin can match on consumer name, 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.

The inherited gateway schema accepts `consumer_group_id`, but API7 Gateway does not expose a customer-manageable consumer-group resource or assign a group ID to consumers. Do not use this identifier type: the value is absent and the plugin rejects the request with `HTTP 401`.

## Capabilities[​](#capabilities "Direct link to Capabilities")

* **Multiple identifier types**: Match on consumer name (default), 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 access controls to a route, a service, or a consumer.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

1. Create a consumer (see [Tutorial: Proxying and Managing API Requests via Plugins](https://docs.api7.ai/api7-gateway/getting-started/tutorial-proxying-api-requests.md#step-4-create-a-consumer)).
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.
4. Prepare a [token from the Dashboard](https://docs.api7.ai/api7-gateway/reference/obtain-dashboard-token.md).

## Configure an Access Control List[​](#configure-an-access-control-list "Direct link to Configure an Access Control List")

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

* Admin API
* ADC

```
curl -k "https://localhost:7443/apisix/admin/routes/acl-restricted-route?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${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 `{gateway_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.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

    labels:

      docs-example: acl-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 \

  --label-selector docs-example=acl-service
```

Synchronize the reviewed configuration:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=acl-service
```

## Key Configuration Parameters[​](#key-configuration-parameters "Direct link to Key Configuration Parameters")

| Field           | Type            | Description                                                                                                                                                                                                                                     |
| --------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`          | `string`        | What `whitelist`/`blacklist` entries refer to. Use `consumer_name` (default), `service_id`, or `route_id`. Do not use the inherited `consumer_group_id` option; API7 Gateway does not assign group IDs and rejects the request with `HTTP 401`. |
| `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](https://docs.api7.ai/hub/consumer-restriction.md).

## Implementation Patterns[​](#implementation-patterns "Direct link to Implementation Patterns")

### Pattern 1: Whitelisting for Private Services[​](#pattern-1-whitelisting-for-private-services "Direct link to 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[​](#pattern-2-blacklisting-malicious-consumers "Direct link to 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[​](#next-steps "Direct link to Next Steps")

* [Learn about RBAC](https://docs.api7.ai/api7-gateway/security-and-compliance/role-based-access-control.md) for more complex permission models.
* [Configure IP Restrictions](https://docs.api7.ai/api7-gateway/security-and-compliance/ip-restrictions-control-plane.md) to add another layer of security at the network level.