You are browsing unreleased documentation. See the latest documentation here.

Consumers

What is a consumer?

A consumer typically refers to an entity that consumes or uses the APIs managed by Kong Gateway. Consumers can be applications, services, or users who interact with your APIs. Since they are not always human, Kong Gateway calls them consumers, because they “consume” the service. Kong Gateway allows you to define and manage consumers, apply access control policies, and monitor their API usage.

Consumers are essential for controlling access to your APIs, tracking usage, and ensuring security. They are identified by key authentication, OAuth, or other authentication and authorization mechanisms. For example, adding a Basic Auth plugin to a service or route allows it to identify a consumer, or block access if credentials are invalid.

You can choose to use Kong Gateway as the primary datastore for consumers, or you can map the consumer list to an existing database to keep consistency between Kong Gateway and your existing primary datastore.

By attaching a plugin directly to a consumer, you can manage specific controls at the consumer level, such as rate limits.

 
flowchart LR

A(Consumer entity)
B(Auth plugin)
C[Upstream service]

Client --> A
subgraph id1[Kong Gateway]
direction LR
A--Credentials-->B
end

B-->C

Use cases for consumers

The following are examples of common use cases for consumers:

Use case	Description
Authentication	Client authentication is the most common reason for setting up a consumer. If you’re using an authentication plugin, you’ll need a consumer with credentials.
Consumer groups	Group consumers by sets of criteria and apply certain rules to them.
Rate limiting	Rate limit specific consumers based on tiers.

Manage consumers

Kong Admin API

Konnect API

decK (YAML)

KIC (YAML)

Kong Manager or Gateway Manager

To create a consumer, call the Admin API’s /consumers endpoint. The following creates a consumer called example-consumer:

curl -i -X POST http://localhost:8001/consumers/ \
  --data username=example-consumer \
  --data custom_id=example-consumer-id \
  --data tags[]=silver-tier

To create a consumer, call the Konnect control plane config API’s /consumers endpoint. The following creates a consumer called example-consumer:

curl -X POST https://{us|eu}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/consumers \
  --data '{
    "custom_id":"example-consumer-id",
    "tags":["silver-tier"],
    "username":"example-consumer"
    }'

The following creates a consumer called example-consumer:

_format_version: "3.0"
consumers:
- custom_id: example-consumer-id
  username: example-consumer
  tags:
    - silver-tier

The following creates a consumer called example-consumer:

apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
 name: example-consumer
 annotations:
   kubernetes.io/ingress.class: kong
username: example-consumer

The following creates a new consumer called example-consumer:

In Kong Manager or Gateway Manager, go to API Gateway > Consumers.
Click New Consumer.
Enter the Username and Custom ID.
Click Create.

Next steps

You will need a credential for each consumer. Find your authentication plugin for the specific instructions for each authentication method. Open the plugin, go to Using this plugin > Basic examples, then choose your preferred tool and follow the instructions.

FAQs

What are credentials, and why do I need them?

Credentials are necessary to authenticate consumers via various authentication mechanisms. The credential type depends on which authentication plugin you want to use.

For example, a Key Authentication plugin requires an API key, and a Basic Auth plugin requires a username and password pair.

What is the difference between consumers and applications?

Applications provide developers the ability to get access to APIs managed by Kong Gateway or Konnect with no interaction from the Kong admin team to generate credentials required.

With consumers, the Kong team creates consumers, generates credentials and needs to share them with the developers that need access to the APIs. You can think as applications as a type of consumer in Kong that allows developers to automatically obtain credentials for and subscribe to the required APIs.

What is the difference between consumers and developers?

Developers are real users of the Dev Portal, whereas consumers are abstractions.

What is the difference between consumers and RBAC users?

RBAC users are users of Kong Manager, whereas consumers are users (real or abstract) of the Gateway itself.

Which plugins can be scoped to consumers?

Certain plugins can be scoped to consumers (as opposed to services, routes, or globally). For example, you might want to configure the Rate Limiting plugin to rate limit a specific consumer, or use the Request Transformer plugin to edit requests for that consumer. You can see the full list in the plugin scopes compatibility reference.

Can you scope authentication plugins to consumers?

No. You can associate consumers with an auth plugin by configuring credentials - a consumer with basic auth credentials will use the Basic Auth plugin, for example. But that plugin must be scoped to either a route, service, or globally, so that the consumer can access it.

Are consumers used in Kuma/Mesh?

No.

Can you manage consumers with decK?

Yes, you can manage consumers using decK, but take caution if you have a large number of consumers.

If you have many consumers in your database, don't export or manage them using decK. decK is built for managing entity configuration. It is not meant for end user data, which can easily grow into hundreds of thousands or millions of records.