Project: APISIX (Orchestration & Management / API Gateway)
File: manage-api-consumers.md

title: Manage API Consumers keywords: API Gateway Apache APISIX Rate Limit Consumer Consumer Group description: This tutorial explains how to manage your single or multiple API consumers with Apache APISIX. <!-- --> This tutorial explains how to manage your single or multiple API consumers with Apache APISIX. Nowadays connect multiple systems, internal services, and third-party applications easily and securely. API consumers are probably the most important stakeholders for API providers because they interact the most with the APIs and the developer portal. This post explains how to manage your single or multiple API consumers with an open-source API Management solution such as . API consumers use an API without integrating it into an APP developed for it. In other words, API consumers are the users of APIs. This means, for example, a marketing department uses a to analyze social media responses to specific actions. It does this with individual, irregular requests to the API provided, as needed. An solution should know who the consumer of the API is to configure different rules for different consumers. In Apache APISIX, the is the most common way for API consumers to access APIs published through its . Consumer concept is extremely useful when you have different consumers requesting the same API and you need to execute various and configurations based on the consumer. By publishing APIs through Apache APISIX API Gateway, you can easily secure API access using consumer keys or sometimes it can be referred to as subscription keys. Developers who need to consume the published APIs must include a valid subscription key in `HTTP` requests when calling those APIs. Without a valid subscription key, the calls are rejected immediately by the API gateway and not forwarded to the back-end services. Consumers can be associated with various scopes: per Plugin, all APIs, or an individual API. There are many use cases for consumer objects in the API Gateway that you get with the combination of its plugins: Enable different authentication methods for different consumers. It can be useful when consumers are trying to access the API by using various authentication mechanisms such as , , or -based auth. Restrict access to API resources for specific consumers. Route requests to the corresponding backend service based on the consumer. Define rate limiting on the number of data clients can consume. Analyze data usage for an individual and a subset of consumers. Let's look at some examples of configuring the rate-limiting policy for a single consumer and a group of consumers with the help of authentication key (API Key) and plugins. For the demo case, we can leverage built on with a single `GET` endpoint (retrieves all products

You can find in all instructions on how to run the sample app. Up to now, I assume that the sample project is up and running. To use consumer object along with the other two plugins we need to follow easy steps: Create a new Consumer. Specify the authentication plugin key-auth and limit count for the consumer. Create a new Route, and set a routing rule (If necessary). Enable key-auth plugin configuration for the created route. The above steps can be achieved by running simple two against APISIX . The first `cmd` creates a new Consumer with API Key based authentication enabled where the API consumer can only make 2 requests against the Product API within 60 seconds. :::note You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```bash adminkey=$(yq '.deployment.admin.adminkey[0].key' conf/config.yaml | sed 's/"//g') ``` ::: ``` shell curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d ' { "username":"consumer1", "plugins":{ "key-auth":{ "key":"auth-one" }, "limit-count":{ "count":2, "time_window":60, "rejected_code":403, "rejected_msg":"Requests are too many, please try again later or upgrade your subscription plan.", "key":"remote_addr" } } }' ``` Then, we define our new Route and Upstream so that all incoming requests to the gateway endpoint `/api/products` will be forwarded to our example product backend service after a successful authentication process. ``` shell curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' { "name": "Route for consumer request rate limiting", "methods": [ "GET" ], "uri": "/api/products", "plugins": { "key-auth": {} }, "upstream": { "type": "roundrobin", "nodes": { "productapi:80": 1 } } }' ``` Apache APISIX will handle the first two requests as usual, but a third request in the same period will return a `403` HTTP code. ``` shell curl http://127.0.0.1:9080/api/products -H 'apikey: auth-one' -i ``` Sample output after calling the API 3 times within 60 sec: ``` shell HTTP/1.1 403 Forbidden Content-Type: text/plain; charset=utf-8 Transfer-Encoding: chunked Connection: keep-alive Server: APISIX/2.13.1 {"error_msg":"Requests are too many, please try again later or upgrade your subscription plan."} ``` Indeed, after reaching the threshold, the subsequent requests are not allowed by APISIX. In Apache APISIX, object is used to manage the visibility of backend services to developers. Backend services are first made visible to groups, and then developers in those groups can view and subscribe to the products that are associated with the groups. With consumer groups, you can specify any number of rate-limiting tiers and apply them to a group of consumers, instead of managing each consumer

Typical scenarios can be different pricing models for your API Monetization like API Consumers with the basic plan are allowed to make 50 API calls per minute or in another use case, you can enable specific APIs for Admins, Developers, and Guests based on their roles in the system. You can create, update, delete and manage your groups using the Apache APISIX Admin REST API . For the sake of the demo, lets create two consumer groups for the basic and premium plans respectively. We can add one or two consumers for each group and control the traffic from consumer groups with the help of the `rate-limiting` plugin. To use consumer groups with rate limiting, you need to: Create one or more consumer groups with a limit-count plugin enabled. Create consumers and assign consumers to groups. Below two curl cmds create consumer groups named `basicplan` and `premiumplan`: Create a Consumer Group Basic Plan. ``` shell curl http://127.0.0.1:9180/apisix/admin/consumergroups/basicplan -H "X-API-KEY: $admin_key" -X PUT -d ' { "plugins": { "limit-count": { "count": 2, "time_window": 60, "rejected_code": 403, "group": "basic_plan" } } }' ``` Create a Consumer Group Premium Plan. ``` shell curl http://127.0.0.1:9180/apisix/admin/consumergroups/premiumplan -H "X-API-KEY: $admin_key" -X PUT -d ' { "plugins": { "limit-count": { "count": 200, "time_window": 60, "rejected_code": 403, "group": "premium_plan" } } }' ``` In the above steps, we set up the rate limiting config for Basic plan to have only 2 requests per 60secs, and the Premium plan has 200 allowed API requests within the the same time window. Create and add first consumer to the Basic group. ``` shell curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d ' { "username": "consumer1", "plugins": { "key-auth": { "key": "auth-one" } }, "groupid": "basicplan" }' ``` Create and add second consumer to the Premium group. ``` shell curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d ' { "username": "consumer2", "plugins": { "key-auth": { "key": "auth-two" } }, "groupid": "premiumplan" }' ``` Create and add third consumer to the Premium group. ``` shell curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d ' { "username": "consumer3", "plugins": { "key-auth": { "key": "auth-three" } }, "groupid": "premiumplan" }' ``` Afterward, we can easily check that the first consumer `Consumer1` in the Basic Plan group will get a `403 HTTP status error` after hitting the 2 API calls per a minute, while the other two consumers in the Premium Plan group can request as many times as until they reach the limit. You can run below cmds by changing auth key for each consumer in the request header: ``` shell curl -i http://127.0.0.1:9080/api/products -H 'apikey: auth-one' ``` ``` shell curl -i http://127.0.0.1:9080/api/products -H 'apikey: auth-two' ``` ``` shell curl -i http://127.0.0.1:9080/api/products -H 'apikey: auth-three' ``` Note that you can also add or remove a consumer from any consumer group and enable other built-in plugins. Read our other to learn more about API Management.