Give a group of clients one limit

When every partner should get the same limit, set it once on a consumer group and put the partners' consumers in it. This guide creates the group partners with a limit of 1000 requests a minute for each member and puts partner-portal in it. At the end, each partner in the group gets 1000 requests a minute of its own, over every route that asks for its key.

Before you start

• This guide starts from orders-api as Route requests to a backend leaves it, with key-auth from Require an API key. The requests below call /orders/42 on orders-api and /invoices/7 on invoices-api, the second route of Limit one client wherever it calls. A plugin from another guide that this page does not name can change the answers below; remove it first or work on a copy of the route.
• The consumers the group is for: partner-portal and a second partner consumer. Create each as Require an API key shows, under its own username, and give it a key as Give a client its key shows.
• The host name of your gateway. In the console it is the first part of the Address line on a route's Overview tab, api.example.com in this page's examples; replace it in every request below.
• The Editor or Environment administrator role in this environment.

Steps

1. Create the group

Under Consumers, open the Consumer groups tab and select New consumer group.

Field	Value
ID	partners
Name	Partners, the name the list of groups shows
Description	Who belongs in it.

Select Create consumer group. The ID cannot be changed later. The group's Labels are for grouping and filtering only; acl reads the labels of each consumer, not of its group.

The General section of the new-consumer-group form, with the ID partners and the name Partners filled in.

2. Give the group its limit

Open the group's Plugins tab, then Add plugin at the top right of the tab. The picker offers no authentication plugin here, because a group's plugins run once the consumer is known. Open the Traffic category, or type limit-count in the search box. Select limit-count, then Configure.

Field	Value	Why
Count	1000	Requests allowed in one window.
Time window	60	The window, in seconds.
Key	consumer_name	Each member is counted under its own name.
Rejected code, under Behavior	429	The status a refused request gets.

Select Add plugin at the bottom of the panel. The group is saved like this:

consumer_group · as the console saves it

{
  "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
    }
  }
}

The example group also carries a description of its own and the label tier, which the steps do not set; yours carries your description and no label. Neither plays a part in the limit.

3. Put the partners' consumers in the group

Open partner-portal under Consumers and select Edit consumer. Under General, pick Partners in Consumer group; the list shows each group by name and ID. Select Save consumer. Do the same for the second partner consumer.

The Edit consumer form of partner-portal, with the consumer group Partners picked.

From the moment you save, the group's limit counts the consumer's requests. A consumer is in one group at most.

Check it

Send a request with the key of partner-portal, then with the key of the second partner, then with the key of partner-portal on invoices-api.

curl

curl -i -L 'https://<gateway host>/orders/42' \
  -H 'x-api-key: <the key of partner-portal>'

With the key of partner-portal

A request with the key of partner-portal, a consumer in the group, is answered 200 with X-RateLimit-Limit: 1000: the group's limit-count counts it, though neither the route nor the consumer carries a limit of its own.

With the key of a second partner

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 on another route

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.

One count for the whole group

To let the partners share one count instead of one each, open the group's Plugins tab. Select limit-count in the list of plugins, then Edit. Under Basics, set Key type to constant and Key to any one word, partners here. Select Save plugin at the bottom of the panel. Every request of every member then counts against the same 1000.

consumer_group · as the console saves it

{
  "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
    }
  }
}

Two members, one count

The members draw on one count: a request of partner-portal lowers the X-RateLimit-Remaining that the second partner's next request is answered with.

Once the count is used

Once the members have used the count between them, every one of them is answered 429, on orders-api and on invoices-api alike.

What to know

• Where a consumer carries the same plugin as its group, the consumer's copy runs 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.
• A limit on the group keeps a member's count over every route that asks for its key. The second request of partner-portal on invoices-api draws on the same 1000 as its request on orders-api.
• That order does not hold for rewriting the request, proxy-rewrite for example. Where the route carries the same plugin, switched on or off, only the route's copy rewrites the request, and only while it is on.
• Putting partner-portal in partners changes the answers of Allow only named clients. On a route that lets only the group mobile-team through, partner-portal is then a consumer in another group and is answered 403 instead of 401.
• A group that consumers still belong to cannot be deleted. Take each consumer out of the group first.

Related

• Limit one client wherever it calls: a limit for one consumer alone.
• Limit requests on a route: one limit for every client of a route.
• Allow only named clients: letting only the members of a group call a route.
• Consumer group in the reference.