Consumers

Uses: Kong Gateway Admin API decK KIC Konnect API Terraform

What is a Consumer?

A Consumer is 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 Gateway Service or Route allows it to identify a Consumer, or block access if credentials are invalid.

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

 
flowchart LR

Consumer(Consumer 
entity)
Service(Gateway 
Service)
Auth(Auth
plugin)
Upstream[Service 
application]
RL["Rate Limiting 
plugin"]

Client --pass
credentials--> Service
subgraph id1 ["`**KONG GATEWAY**`"]
    subgraph padding[ ]

subgraph Authenticate ["Consumer Identity Added"]
    direction LR
    Service --> Auth
    Auth--identify 
    Consumer-->Consumer
    end
end

Consumer--> RL
end
RL --apply 
per-Consumer
rate limiting--> Upstream

style Authenticate stroke-dasharray: 5 5
style padding stroke:none!important,fill:none!important

Use cases for Consumers

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.
Rate limiting	Rate limit specific Consumers based on tiers.
Transformation	Add or remove values from response bodies based on the Consumer.

Centrally-managed Consumers v3.10+

Consumers can be scoped to a Konnect region and managed centrally, or be scoped to a Control Plane in Gateway Manager.

Centralized Consumer management provides the following benefits:

Set up a Consumer identity centrally: Only define a Consumer once, instead of defining it in multiple Control Planes.
Avoid conflicts from duplicate Consumer configuration: Users don’t need to replicate changes to Consumer identity in multiple Control Planes and Consumer configuration doesn’t conflict.
Reduce configuration sync issues between the Control Plane and the Data Planes: Consumers that are managed centrally aren’t part of the configuration that is pushed down from the Control Plane to the Data Planes, so it reduces config size and latency.

Centrally managed Consumers exist outside of Control Planes, so they can be used across Control Planes.

You can manage Consumers centrally using the Konnect Consumers API. Only Org Admins and Control Plane Admins have CRUD permissions for these Consumers.

When you create a Consumer centrally, you must assign it to a realm. A realm groups Consumers around an identity, defined by organizational boundaries, such as a production realm or a development realm. Realms are connected to a geographic region in Konnect. Additionally, centrally managed Consumers must have a specific Key Authentication configuration set up to allow these Consumers to authenticate.

For a complete tutorial, see Create a centrally-managed Consumer in Konnect.

Note: If you are using KIC to manage your Data Plane nodes in Konnect, ensure that you configure the cluster_telemetry_endpoint in the Data Plane. You can find your specific cluster_telemetry_endpoint in Gateway Manager, in the Data Plane node setup instructions.

Consumer schema

Set up a Consumer

The following creates a new Consumer called example-consumer:

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

To create a Consumer, call the Admin API’s /consumers endpoint.

curl -i -X POST http://localhost:8001/consumers/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "custom_id": "example-consumer-id",
      "username": "example-consumer",
      "tags": [
        "silver-tier"
      ]
    }
    '

To create a Consumer, call the Konnect control plane config API’s /consumers endpoint.

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/consumers/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "custom_id": "example-consumer-id",
      "username": "example-consumer",
      "tags": [
        "silver-tier"
      ]
    }
    '

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: example-consumer
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/tags: silver-tier
custom_id: example-consumer-id
username: example-consumer
" | kubectl apply -f -

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

resource "konnect_gateway_consumer" "my_consumer" {
  custom_id = "example-consumer-id"
  username = "example-consumer"
  tags = ["silver-tier"]

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

The following creates a new consumer called example-consumer:

In Kong Manager or Gateway Manager, go to Consumers.
Click New Consumer.
Enter the Username example-consumer and Custom ID example-consumer-id.
Click Save.

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 Authentication 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 the required credentials. Applications are managed using the Developer Portal.

With Consumers, the Kong team creates Consumers, generates credentials, and shares them with the developers that need access to the APIs.

What is the difference between Consumers and Developers?

A developer is a person that has registered for a Developer Portal. They can create applications and manage credentials themselves.

Consumers are a part of your Kong Gateway configuration and are managed by your administrators.

What is the difference between Consumers and RBAC Users?

RBAC Users are users of Kong Manager, whereas Consumers are users of the services proxied by the Gateway itself.

Which plugins can be scoped to Consumers?

Most plugins can be scoped to Consumers, with the exception of authentication plugins and plugins that control routing.

You can see the full list in the plugin scopes compatibility reference.

Can you scope authentication plugins to Consumers?

No. Authentication plugins must be scoped to either a Route, Service, or globally.

Can you manage Consumers with decK?

Yes, you can manage Consumers using decK, but take caution if you have a large number of Consumers as the sync time will be high.

To manage a large number of Consumers using decK, we recommend a federated configuration management approach where Consumers are placed in to Consumer Groups and managed separately from the rest of your configuration.