--- title: AI Consumer Groups description: AI Consumer Groups for AI Gateway. url: "/ai-gateway/entities/ai-consumer-group/" canonical_url: "/ai-gateway/entities/ai-consumer-group/" content_type: reference min_version: ai-gateway: '2.0' products: - AI Gateway tools: - Konnect API - kongctl canonical: true works_on: - konnect --- # AI Consumer Groups ## What is an AI Consumer Group? 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](/ai-gateway/entities/ai-policy/) 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](/ai-gateway/policies/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
## Manage AI Consumer Groups AI Consumer Groups can be created and managed through: * Konnect UI * AI Gateway API: `/v1/ai-gateways/{aiGatewayId}/consumer-groups` * [kongctl](/kongctl/) For configuration examples and step-by-step setup instructions, see [Set up an AI Consumer Group](#set-up-an-ai-consumer-group). ## Use cases for using AI Consumer Group Common use cases for AI Consumer Groups: ### Subscription tier management Description: Create AI Consumer Groups for different subscription [tiers](/ai-gateway/enforce-tiered-ai-budgets-with-kong-identity/) (for example, Bronze, Gold, Enterprise). Assign different rate limits, model access restrictions, and token quotas to each tier without configuring individual AI Consumers. ### Team-based access control Description: Organize AI Consumers by team or department. Gate access to specific [AI Models](/ai-gateway/entities/ai-model/), [AI Agents](/ai-gateway/entities/ai-agent/), or [AI MCP Servers](/ai-gateway/entities/ai-mcp-server/) at the group level, so teams only access the resources they need. ### AI safety and governance AI Policies Description: Apply group-level AI Policies for prompt validation, PII detection, and content filtering. For example, apply stricter guardrails to public-facing groups while allowing more permissive configurations for internal teams. See the [AI Policies hub](/ai-gateway/policies/) for available policy types. ### Cost and quota management Description: Enforce per-group token limits, rate limits, and usage quotas. Track spending and resource usage by AI Consumer Group to manage AI API costs at scale. ### Centralized AI Policy management Description: Attach AI Policies once at the group level rather than managing them on every individual AI Consumer. Simplifies configuration and ensures consistency across all group members. ## Membership 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. ## Attach AI Policies 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`](#schema-aigateway-consumer-group-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](/ai-gateway/entities/ai-policy/) reference. ## Use in parent entity ACLs To restrict access to specific [AI Models](/ai-gateway/entities/ai-model/), [AI Agents](/ai-gateway/entities/ai-agent/), or [AI MCP Servers](/ai-gateway/entities/ai-mcp-server/) 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. ## Set up an AI Consumer Group 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. ### Konnect API To create a Consumer Group, call the Konnect [AI Gateway API's `/consumer-groups` endpoint](/api/konnect/ai-gateway/#/operations/create-ai-consumer-group). ```bash 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": [] } ' ``` Make sure to replace the following placeholders with your own values: * `region`: Geographic region where your Kong Konnect is hosted and operates. * `KONNECT_TOKEN`: Your Personal Access Token (PAT) associated with your Konnect account. * `AIGatewayId`: The `id` of the AI Gateway. See the [Konnect AI Gateway API reference](/api/konnect/ai-gateway/) to learn about region-specific URLs and personal access tokens. ### kongctl ```yaml ai_gateway_consumer_groups: - ref: internal-teams ai_gateway: !lookup {id: !env AI_GATEWAY_ID} display_name: Internal Teams name: internal-teams policies: [] ``` {: data-file="consumer_group.yaml" data-tool="kongctl" } Make sure to replace the following placeholders with your own values: * `AI_GATEWAY_ID`: The `id` of your AI Gateway. ### UI The following creates a new AI consumer group. Suggested values are shown in backticks. 1. In Konnect, navigate to [AI Gateway](https://cloud.konghq.com/ai-manager/v2/gateways) in the sidebar. 1. Select an AI Gateway. 1. Navigate to **Consumers**. 1. Select the **Groups** tab. 1. Click **New consumer group**. 1. Enter a **Display name** (for example: `Internal Teams`). 1. Optional. Select one or more consumers to add to the group. 1. Click **Create**. > This creates an empty AI Consumer Group with no members. To add AI Consumers to it, see [Membership](#membership). There's no `consumers` field on the AI Consumer Group itself; membership is set through a separate endpoint. ## Schema ```json { "type": "object", "properties": { "display_name": { "description": "The display name for this consumer group instance.", "type": "string", "example": "Dev Users Group", "maxLength": 256, "minLength": 1 }, "name": { "description": "A user-defined unique identifier for this consumer group, used as a stable human-readable reference. This value is immutable after creation.", "example": "dev-users", "allOf": [ { "$ref": "#/components/schemas/AIGatewayEntityIdentifier" } ] }, "policies": { "$ref": "#/components/schemas/AIGatewayPolicyReferences" }, "labels": { "$ref": "#/components/schemas/PublicLabels" }, "managed_by": { "$ref": "#/components/schemas/ManagedBy" }, "id": { "$ref": "#/components/schemas/UUID" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt" } }, "required": [ "display_name", "name", "id", "created_at", "updated_at" ] } ``` ## FAQs - How is an AI Consumer Group different from a Kong Gateway Consumer Group? The AI Gateway surface adds the entity convention ([`display_name`](#schema-aigateway-consumer-group-display-name), [`name`](#schema-aigateway-consumer-group-name), [`labels`](#schema-aigateway-consumer-group-labels)) and a required [`policies`](#schema-aigateway-consumer-group-policies) array for attaching AI Policies at the group scope. - Can I edit the underlying Kong Consumer Group that AI Gateway generates? No. The generated Kong Consumer Group is protected from direct modification through the standard `/consumer-groups` Admin API. Update the AI Consumer Group instead. - How do I assign an AI Consumer to an AI Consumer Group? Either add the AI Consumer through the AI Consumer Group's `consumers` sub-resource (`POST /ai-gateways/{aiGatewayId}/consumer-groups/{consumerGroupId}/consumers`), or set the AI Consumer's group membership directly (`PUT /ai-gateways/{aiGatewayId}/consumers/{consumerIdOrName}/consumer-groups`). These aren't fields on the AI Consumer or AI Consumer Group entity bodies themselves. They're managed through these dedicated endpoints. - Can an AI Consumer belong to multiple AI Consumer Groups? Yes. The `consumer_groups` list accepted by `PUT /ai-gateways/{aiGatewayId}/consumers/{consumerIdOrName}/consumer-groups` can include more than one AI Consumer Group name. - How do I attach AI Policies to an AI Consumer Group? Add the AI Policy's `name` or `id` to the AI Consumer Group's [`policies`](#schema-aigateway-consumer-group-policies) array. The AI Policy runs when a member of the group is identified during a request. See the [AI Policy entity](/ai-gateway/entities/ai-policy/) reference. - How do I gate access to an AI Model, AI Agent, or AI MCP Server with an AI Consumer Group? Add the AI Consumer Group's name to the parent entity's `access.acls.allow` or `access.acls.deny` list. For AI Models and AI Agents, configure exactly one of `allow` or `deny`. For AI MCP Servers, both can be set simultaneously. ACLs accept AI Consumer, AI Consumer Group, and Authenticated Group names. See the [AI Model entity](/ai-gateway/entities/ai-model/) reference. ## Related Resources - [About AI Gateway](/ai-gateway/) - [AI Consumer entity](/ai-gateway/entities/ai-consumer/) - [AI Model entity](/ai-gateway/entities/ai-model/) - [AI Policy entity](/ai-gateway/entities/ai-policy/) - [Kong Gateway Consumer Group entity](/gateway/entities/consumer-group/) - [Enforce tiered AI budgets on AI Models with Kong Identity](/ai-gateway/enforce-tiered-ai-budgets-with-kong-identity/)