Skip to main content

Version: 3.8.0

Consumer Groups

In this document, you will learn the basic concept of consumer groups in APISIX and their common use cases. You will be introduced to a few relevant concepts, including how to pass consumer group information to upstream and consumer group access restriction.

Explore additional resources at the end of the document for more information on related topics.


In APISIX, a consumer group corresponds to a group of consumers sharing the same plugin configurations, such as access control and rate limiting policies. Consumers can be added to a consumer group by referring to the consumer group ID in their configurations. This allows for easier management of APIs and helps to reduce redundancies in consumer configurations.

A few sample use cases of consumer groups are:

  • Implementing API monetization with different pricing models
  • Implementing role-based access control (RBAC) for different roles, such as admins, developers, and guests
  • Grouping consumers based on other shared functionalities

The following diagram illustrates the concept of consumer groups with an API monetization example that has three consumers, JohnDoe, JaneDoe, and FetchBot. John and Jane are human consumers in the basic plan that share a lower API quota, and the bot is in the premium plan with a higher API quota:

Consumer groups usage for a basic plan and a premium plan

By using consumer groups, you do not need to repetitively configure limit-count on each consumer.

Passing Consumer Group Information to Upstream

Similar to passing consumer information to upstream, you can use proxy-rewrite plugin on consumer groups to include the needed information in the header:


Consumer Group Access Restriction

You can control request access to your API by imposing restrictions based on consumer group ID, HTTP methods, or other parameters in the consumer-restriction plugin.

For example, if you want to strictly restrict the HTTP method for a consumer group called cg-data-uploading to use PUT, you can update the plugin's configuration as follows:


The consumer-restriction plugin can also be used with consumers, routes, services, and plugin global rules.

For more details on the plugin usage, please refer to the plugin reference guide (coming soon).

Additional Resource(s) Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.


API7 Cloud

SOC2 Type IRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation