← Gateway Entities

Consumers

Uses: Kong Gateway decK KIC Terraform

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.

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 -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.

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

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 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.

Consumers

What is a consumer?

Use cases for consumers

Schema

Set up a Consumer

FAQs

Did this doc help?

Help us make these docs great!

Still need help