Group by Header Quota

Group by Header Quota enables dynamic quota allocation by grouping requests using the group_by_header field. This feature allows you to define different rate limits for various user types while maintaining a shared total quota.

For example, if your company operates as a Consume on Behalf of (CoBo) company, this functionality helps you manage API traffic for multiple customers who each have their own API key but access the same API provider. By grouping requests per customer, you can prevent a single customer from exhausting the entire quota, ensuring fair API access for all.

Use Cases

In this use case, Company1, Company2, and Company3 each have their own API key but share the same quota for api.website.com/*. To ensure fair usage, we use the group_by_header field to segment the quota based on the x-lunar-user-role header, which identifies which company each request belongs to.

In the example below, the x-lunar-user-role header is used to allocate quotas dynamically, allowing each company to make up to 12 requests per minute. This means that even though all companies access the same API, their requests are counted separately, ensuring that no single company can consume more than its fair share of the total quota.

/etc/lunar-proxy/quotas/{fileName}.yaml

quotas:
  - id: HeaderBasedQuota
    filter:
      url: api.website.com/*
    strategy:
      fixed_window:
        max: 12
        interval: 1
        interval_unit: minute
        group_by_header: 'x-lunar-user-role'