Consumer group
Consumer groups hold plugins that several consumers share.
consumer_groupWhat a consumer group is
A consumer group gathers consumers that are treated alike, for example all your partners or the apps of one team. Its plugins run for every consumer in it, once a plugin on the route like key-auth has named the consumer. A limit-count on the group gives each partner the same limit without adding it to each consumer.
A consumer joins under Consumer group, and a limit-count of its own counts instead of the group's. consumer-restriction can let a route take only the consumers of one group. Authentication shows how the pieces fit together.
When to use it
- Every partner, or every app of one team, should get the same plugin, for example 1000 requests a minute each.
- The apps of one team should share one count between them.
- A route should let in only the consumers of one team: consumer-restriction compares the group's ID.
Not for a limit or another plugin for one client alone — see Consumer (Consumers identify the callers of your APIs; their credentials live under each consumer) or plugins that several routes share, whoever calls them — see Service (Services hold the upstream and plugins that several routes share).
Guides
Pages that walk through a job with a consumer group, step by step.
- Allow only named clientsLet only the consumers you list call a route, by name or by consumer group.
- Give a group of clients one limitPut consumers in a group and set the limit once on the group.
Set it up
Limit every partner to 1000 requests a minute
Each consumer in the group is counted under its own name, over every route that asks for its key, once key-auth has named it.
Under General set ID to partners, set Name to Partners, set Description to Integration partners, each counted under its own consumer name and fill Labels as in the JSON below. Once it is created, open its Plugins tab and add limit-count with its settings from the JSON below.
{
"id": "partners",
"name": "Partners",
"desc": "Integration partners, each counted under its own consumer name",
"labels": {
"tier": "partner"
},
"plugins": {
"limit-count": {
"count": 1000,
"time_window": 60,
"key": "consumer_name",
"rejected_code": 429
}
}
}
What you will see
- A request with the key of partner-portal, a consumer in the group, is answered
200withX-RateLimit-Limit: 1000: the group's limit-count counts it, though neither the route nor the consumer carries a limit of its own. - A second partner in the group has a count of its own: after a request of partner-portal, the second partner's first request is answered with
X-RateLimit-Remaining: 999. - partner-portal's requests on another route that asks for its key, such as invoices-api, are counted in the same 1000: its second request is answered with
X-RateLimit-Remaining: 998.
More scenarios
Hold the partners to 1000 requests a minute together
With Key type constant every request of every consumer in the group is counted under the one Key, partners here, over every route that asks for their keys.
Under General set ID to partners, set Name to Partners and set Description to Integration partners, sharing one count. Once it is created, open its Plugins tab and add limit-count with its settings from the JSON below.
{
"id": "partners",
"name": "Partners",
"desc": "Integration partners, sharing one count",
"plugins": {
"limit-count": {
"count": 1000,
"time_window": 60,
"key_type": "constant",
"key": "partners",
"rejected_code": 429
}
}
}
What you will see
- The members draw on one count: a request of partner-portal lowers the
X-RateLimit-Remainingthat the second partner's next request is answered with. - Once the members have used the count between them, every one of them is answered
429, on orders-api and on invoices-api alike.
Things to know
- Plugins — Where a consumer carries the same limit-count as its group, the consumer's copy counts instead of the group's, and the group's instead of the route's. On a route whose own limit is 100, a member of a group with 1000 is counted by the group's, and a member with 5000 of its own by that.
- Plugins — A plugin that rewrites the request, for example proxy-rewrite, does not follow that order. Where the route carries it too, only the route's copy rewrites the request, whatever the consumer or its group carries.
- Plugins — A limit-count on the group keeps a member's count over every route that asks for its key:
partner-portaloninvoices-apidraws on the same 1000 as onorders-api. - Labels — acl does not read a label on the group: a member with no label of its own is refused by an allow list even when its group carries the label.
- ID — consumer-restriction compares the group's ID, not its Name: a consumer whose group carries the listed name under another ID is refused.
- A consumer group that consumers still belong to cannot be deleted: g8 refuses the delete while they still use it. Take each consumer out of the group first.
Settings
The fields as the console shows them, section by section.
General
idstring or integerRequiredLetters, digits, dots, hyphens and underscores, up to 64 characters. The ID cannot be changed later.
pattern
^[a-zA-Z0-9-_.]+$namestringRequireddescstringlabelsobjectKey and value pairs of your own, for grouping and filtering. They change nothing about traffic. An object whose keys are any name, each with a string as its value.
Plugins
Plugins on this consumer group are managed in the Plugins tab once the consumer group exists. Every consumer in the group runs them once the request is authenticated.
pluginsobjectRequiredThe plugins of this consumer group, keyed by plugin name. The engine runs them by their priority, not by the order they are written in.