# Consumers

In this document, you will learn the basic concepts of consumers in APISIX and why you need them. You will be introduced to a few relevant concepts, including how to pass consumer information to upstream, consumer access restriction, as well as consumer authentication and authorization.

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

## Overview[​](#overview "Direct link to Overview")

In APISIX, a *consumer* object represents a user, application, or host that sends requests to the API gateway and consumes backend services. Consumers are typically used with authentication plugins, which identify a consumer from request credentials and make its plugin configuration available while APISIX processes the request.

Consumer objects come in handy if you have different consumers sending requests to your system, and you need APISIX to perform certain functions, such as rate limiting, based on consumers. These functionalities are provided by APISIX plugins configured in consumers.

The following diagram illustrates an example of APISIX with one [`key-auth`](https://docs.api7.ai/hub/key-auth.md) enabled route and two consumers, John and Jane. John and Jane each authenticates to the route with their [credentials](https://docs.api7.ai/apisix/key-concepts/credentials.md). Only authenticated requests are then allowed to access the upstream resource:

![consumers diagram](https://static.api7.ai/uploads/2024/09/12/nJhSZ7tC_consumers-label-udpated.svg)

The configuration above ensures if a request is sent to APISIX:

* without any key or with a wrong key, the request is rejected.
* with `john-key`, the request is authenticated and forwarded to the upstream service.
* with `jane-key`, the request is authenticated and forwarded to the upstream service. The rate limiting plugin [`limit-count`](https://docs.api7.ai/hub/limit-count.md) on the consumer also takes effect, limiting the number of requests to a maximum of 2 within any 5-second window. If the rate limit threshold is exceeded, the request will be rejected.

Note that when a consumer is successfully authenticated, APISIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Identifier`, `X-Consumer-Custom-ID`, to the request, before proxying it to the upstream service. The upstream service will be able to differentiate between consumers and implement additional logic as needed. If any of these values is not available, the corresponding header will not be added.

## Passing Consumer Information to Upstream[​](#passing-consumer-information-to-upstream "Direct link to Passing Consumer Information to Upstream")

After authentication, APISIX automatically sends the available consumer identity in `X-Consumer-Username`, `X-Credential-Identifier`, and `X-Consumer-Custom-ID`. Use the `proxy-rewrite` plugin when an upstream needs additional consumer fields, a different header name, or a derived value. For example, the following configuration copies the consumer name to `X-Consumer-Name`:

```
{

  "plugins":{

    ...,

    "proxy-rewrite":{

      "headers":{

        "set":{

          "X-Consumer-Name":"$consumer_name"

        }

      }

    }

  }

}
```

## Consumer Access Restriction[​](#consumer-access-restriction "Direct link to Consumer Access Restriction")

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

For example, if you want to blacklist `Jane` from accessing your upstream service without changing any consumers configuration in the example from [overview](#overview), you can update the plugin's configuration in the route to the following:

```
{

  "plugins":{

    "key-auth":{},

    "consumer-restriction":{

      "blacklist":["Jane"]

    }

  }

}
```

Or, if you want to strictly allow `FetchBot`'s access by HTTP GET method, you can update the plugin's configuration (in either the route or the consumer) to the following:

```
{

  "plugins":{

    ...,

    "consumer-restriction":{

      "allowed_by_methods":[

        {

          "user":"FetchBot",

          "methods":["GET"]

        }

      ]

    }

  }

}
```

The [`consumer-restriction`](https://docs.api7.ai/hub/consumer-restriction.md) plugin can also be used with [routes](https://docs.api7.ai/apisix/key-concepts/routes.md), [services](https://docs.api7.ai/apisix/key-concepts/services.md), and [consumer groups](https://docs.api7.ai/apisix/key-concepts/consumer-groups.md).

## Authentication & Authorization[​](#authentication--authorization "Direct link to Authentication & Authorization")

There are two main design patterns for building authentication and authorization in an APISIX-based architecture.

The first and most commonly adopted approach is to authenticate and authorize requests through a third-party [identity provider (IdP)](https://en.wikipedia.org/wiki/Identity_provider), such as [Keycloak](https://www.keycloak.org):

![APISIX integration with an IdP](https://static.api7.ai/uploads/2023/03/16/N8W31TWC_consumers-auth1.svg)

<br />

Configure authentication and authorization plugins on the route or service that protects the API. Attaching multiple authentication plugins to a consumer does not enforce a chain of IdPs.

When an API should accept more than one authentication method, use a supported orchestration plugin such as [`multi-auth`](https://docs.api7.ai/hub/multi-auth.md) on the route or service. Plugin [execution order](https://docs.api7.ai/apisix/key-concepts/plugins.md#plugins-execution-order) is determined by priority and can be overridden with [`_meta.priority`](https://docs.api7.ai/apisix/reference/plugin-common-configurations.md#_metapriority), but execution order alone does not combine authentication results.

The second and a more basic approach is to perform authentication and authorization on the API gateway itself, using `key-auth`, `basic-auth`, `jwt-auth`, `hmac-auth` plugins:

![APISIX performs auth without IdP](https://static.api7.ai/uploads/2023/03/16/UGxTDGut_consumers-auth2.svg)

<br />

When APISIX authenticates requests with consumer credentials, consumer objects store identity and credential objects store authentication plugin configuration. Route or service authentication plugins use this data during authentication. After authentication, APISIX merges applicable non-authentication plugin configurations from the consumer and consumer group.

The Admin API rejects a write that would give two consumers or credentials the same lookup key for `key-auth`, `basic-auth`, `jwt-auth`, `hmac-auth`, or LDAP authentication. The response is `400 Bad Request`. The check uses the locally watched consumer view, so concurrent writes can still race, and values supplied through Secret or environment references cannot be resolved for this comparison. Audit existing consumers before an upgrade if those plugins are in use.

For details about how to configure authentication and authorization for your specific needs, please refer to the [authentication section](https://docs.api7.ai/apisix/how-to-guide/authentication/implement-basic-auth.md) in How-To Guides.

## Additional Resource(s)[​](#additional-resources "Direct link to Additional Resource(s)")

* Getting Started - [Configure Key Authentication](https://docs.api7.ai/apisix/getting-started/key-authentication.md)
* Admin API - [Consumers](https://docs.api7.ai/apisix/reference/admin-api.md#tag/Consumers)
* [`consumer-restriction`](https://docs.api7.ai/hub/consumer-restriction.md) plugin
* Key Concepts - [Credentials](https://docs.api7.ai/apisix/key-concepts/credentials.md)
