Consumers

Uses: Kong Gateway Admin API decK KIC Konnect API Terraform

What is a Consumer?

A Consumer is an entity that identifies an external client that consumes or uses the APIs managed by Kong Gateway. Consumers can represent 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.

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

* Additional properties are NOT allowed.
created_atinteger

Unix epoch when the resource was created.

custom_idstring

Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. You must send either this field or username with the request.

idstring
tagsarray[string]

An optional set of strings associated with the Consumer for grouping and filtering.

updated_atinteger

Unix epoch when the resource was last updated.

usernamestring

The unique username of the Consumer. You must send either this field or custom_id with the request.

Set up a Consumer

FAQs

Did this doc help?

Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!