AI Consumer Groups

An AI Consumer Group is the AI Gateway entity that represents a collection of AI Consumers grouped for the purpose of applying shared AI Policies and access controls.

By grouping AI Consumers together, you eliminate the need to manage AI Policies and access controls individually, providing a scalable, efficient approach to AI governance. With AI Consumer Groups, you can scope AI Policies to specifically defined groups, making configurations and customizations more flexible.

For example, you could define three groups (Bronze, Gold, and Enterprise) and attach an AI Rate Limiting Advanced policy to each with different token quotas and cost budgets. Without AI Consumer Groups, you would attach a separate AI Rate Limiting Advanced policy to each individual AI Consumer. In production, that could be thousands of individual policy attachments instead of three group-level ones.

 
flowchart LR
    A((AI Consumers 1-5))

    B("AI Consumer Group Gold
AI Consumer 1, AI Consumer 2, AI Consumer 5")

    C("AI Consumer Group Bronze
AI Consumer 3, AI Consumer 4")

    D["AI Rate Limiting Advanced
1M tokens/hour
AND
$100/hour budget"]
    E["AI Rate Limiting Advanced
100K tokens/hour
AND
$10/hour budget"]
    F("AI Model
GPT-4")
    H["OpenAI
Service"]

    A--> B & C
    subgraph id1 ["AI Gateway"]
    direction LR
    B --> D --> F
    C --> E --> F
    end

    F --> H
  

AI Consumer Groups can be created and managed through:

• Konnect UI
• AI Gateway API: /v1/ai-gateways/{aiGatewayId}/consumer-groups
• kongctl

For configuration examples and step-by-step setup instructions, see Set up an AI Consumer Group.

Common use cases for AI Consumer Groups:

To organize AI Consumers by team, department, or tier, add them to an AI Consumer Group. Membership isn’t a field on either entity’s body. Manage it through dedicated sub-resource endpoints: add a Consumer to a group with POST /ai-gateways/{aiGatewayId}/consumer-groups/{consumerGroupId}/consumers, or set the full list of groups a Consumer belongs to with PUT /ai-gateways/{aiGatewayId}/consumers/{consumerIdOrName}/consumer-groups. A single AI Consumer can belong to multiple AI Consumer Groups, allowing flexible organizational schemes.

To apply the same AI Policies (rate limits, prompt validation, PII detection) to multiple consumers at once, attach them to the AI Consumer Group. When a member of the group makes a request, AI Gateway applies all attached AI Policies before routing the request. Add an AI Policy’s name or id to the AI Consumer Group’s policies array.

You can attach multiple AI Policies to a single AI Consumer Group with different configurations, and each runs independently. For supported policy types and how AI Policies attach to other entities, see the AI Policy entity reference.

To restrict access to specific AI Models, AI Agents, or AI MCP Servers by AI Consumer Group (for example, allowing only Gold tier AI Consumers to access premium models), use ACLs. The access.acls field on these entities accepts AI Consumer Group names alongside AI Consumer and Authenticated Group names. For AI Models and AI Agents, configure exactly one of access.acls.allow to permit access or access.acls.deny to block it. You can’t set both at the same time. For AI MCP Servers, access.acls supports setting allow, deny, or both.

AI Consumer Group membership is resolved after the request is authenticated and the AI Consumer is identified.

The following example creates an AI Consumer Group. You can attach AI Policies through the Konnect UI or by adding their name or id to the policies array.

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/consumer-groups \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "Internal Teams",
      "name": "internal-teams",
      "policies": []
    }
    '

ai_gateway_consumer_groups:
  - ref: internal-teams
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Internal Teams
    name: internal-teams
    policies: []

This creates an empty AI Consumer Group with no members. To add AI Consumers to it, see Membership. There’s no consumers field on the AI Consumer Group itself; membership is set through a separate endpoint.