AI Consumers

Uses: AI Gateway kongctl Konnect API

What is an AI Consumer?

An AI Consumer is the AI Gateway entity that identifies an external client consuming or using the AI APIs you publish through AI Gateway. Consumers can represent applications, services, or users who interact with your AI Models, AI Agents, and AI MCP Servers.

AI Consumers are essential for controlling access to your AI APIs, tracking usage, and ensuring security. They are identified through authentication credentials (API keys or OAuth), allowing AI Gateway to authenticate requests and apply Consumer-specific controls. By creating AI Consumers and organizing them into AI Consumer Groups, you can manage access controls at scale, attach AI Policies for governance and security, and monitor token usage per Consumer.

Use cases for AI Consumers

Common use cases for enforcing controls at the AI Consumer level:

Use case	Description
Model access control	Control which clients can access which AI Models, restricting access by team, application tier, or use case.
AI safety and guardrails	Apply prompt validation, PII detection, and content filtering at the AI Consumer level using AI Policies.
Token and cost control	Apply per-consumer rate limits and quotas to prevent token overages and control costs by AI Consumer tier.
AI request transformation	Normalize or transform AI requests and responses per AI Consumer (for example, format prompts, inject system instructions, sanitize outputs).
Audit and compliance	Track which clients are using which AI Models, monitor for policy violations, and maintain audit logs for compliance and analytics.

Manage AI Consumers

AI Consumers can be created and managed through:

Konnect UI
AI Gateway API: /v1/ai-gateways/{aiGatewayId}/consumers
kongctl

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

Authentication type

Choose an authentication method based on your deployment needs. Set the type field to declare which credential family AI Consumers will use:

Type	Use case
`api-key`	Simple, stateless authentication for internal services or mobile apps using a shared secret.
`oauth`	Federated identity with an external OIDC provider. AI Gateway accepts any standards-compliant OAuth 2.0 / OpenID Connect provider configured through the `openid-connect` auth strategy, or for MCP traffic through the AI MCP OAuth2 Policy. The AI Consumer’s own `custom_id` field maps to the OAuth provider’s user identifier (for example, an OIDC Client ID or `sub` claim).

api-key AI Consumers authenticate through one or more api-key Credentials created via the credentials endpoint. oauth AI Consumers don’t have Credentials. Set custom_id directly on the AI Consumer instead.

AI Consumer Group membership

To apply AI Policies and access controls to multiple AI Consumers at once, organize them into AI Consumer Groups. An AI Consumer can belong to multiple AI Consumer Groups, letting you manage access controls by team, application, or environment without duplicating configurations.

Manage AI Consumer Group membership through the AI Consumer Group entity.

Attach Policies

To enforce governance, security, or observability controls at the AI Consumer level, attach AI Policies. When an AI Consumer makes a request, AI Gateway applies any AI Policies attached to that AI Consumer before routing the request.

Attach an AI Policy by adding its name or id to the AI Consumer’s policies array. You can attach multiple AI Policies to a single AI Consumer. Each AI Policy runs independently, allowing you to layer controls for rate limiting, request validation, PII redaction, and other governance needs.

For supported policy types and how AI Policies attach to other entities, see the AI Policy entity reference or browse all available AI Policies in the AI policies hub.

Set up an AI Consumer

The following example creates an api-key AI Consumer. After creating it, add one or more API key Credentials (see Create Consumer Credentials).

Consumer Group membership isn’t set on the Consumer itself, as there’s no consumer_groups field on this request. To add this Consumer to an AI Consumer Group, use the AI Consumer Group entity’s /consumers endpoint after creation. See the AI Consumer Group entity for more information.

To create a Consumer, call the Konnect AI Gateway API’s /consumers endpoint.

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/consumers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "Mobile App - Production",
      "name": "mobile-app-production",
      "type": "api-key",
      "policies": []
    }
    '

Copied!

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 to learn about region-specific URLs and personal access tokens.

consumer.yaml

Copied!

ai_gateway_consumers:
  - ref: mobile-app-production
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Mobile App - Production
    name: mobile-app-production
    type: api-key
    policies: []

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

AI_GATEWAY_ID: The id of your AI Gateway.

The following creates a new AI Consumer. Suggested values are shown in backticks:

In Konnect, navigate to AI Gateway in the sidebar.
Select an AI Gateway.
Navigate to Consumers.
Click New consumer.
Select a consumer Type (for example: api-key).
Enter a Display name (for example: Mobile App - Production) and Custom ID (for example: ``).
If you selected API key, optionally enter a Display name for the key and click Generate key, then click Create key. Click Skip instead if you don’t want to add a key yet.
If you selected OAuth, click Create. Authentication for this consumer type is handled by an OpenID Connect policy matched to the consumer’s Custom ID, not by a key generated here.

The following example creates an oauth AI Consumer. Set custom_id to the identifier your OIDC provider issues (for example, a sub claim); this is how AI Gateway maps an incoming token to this AI Consumer. oauth AI Consumers don’t have Credentials.

To create a Consumer, call the Konnect AI Gateway API’s /consumers endpoint.

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/consumers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "OAuth User 1",
      "name": "oauth-user-1",
      "type": "oauth",
      "custom_id": "user-id-from-oidc-provider",
      "policies": []
    }
    '

Copied!

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 to learn about region-specific URLs and personal access tokens.

consumer.yaml

Copied!

ai_gateway_consumers:
  - ref: oauth-user-1
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: OAuth User 1
    name: oauth-user-1
    type: oauth
    custom_id: user-id-from-oidc-provider
    policies: []

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

AI_GATEWAY_ID: The id of your AI Gateway.

The following creates a new AI Consumer. Suggested values are shown in backticks:

In Konnect, navigate to AI Gateway in the sidebar.
Select an AI Gateway.
Navigate to Consumers.
Click New consumer.
Select a consumer Type (for example: oauth).
Enter a Display name (for example: OAuth User 1) and Custom ID (for example: user-id-from-oidc-provider).
If you selected API key, optionally enter a Display name for the key and click Generate key, then click Create key. Click Skip instead if you don’t want to add a key yet.
If you selected OAuth, click Create. Authentication for this consumer type is handled by an OpenID Connect policy matched to the consumer’s Custom ID, not by a key generated here.

Create Consumer Credentials

After creating an api-key AI Consumer, create one or more Credentials for authentication. Credentials are managed through a separate endpoint and only support type: api-key. oauth AI Consumers authenticate through their custom_id field instead (see Set up an AI Consumer).

curl -X POST "https://us.api.konghq.com/v1/ai-gateways/$AI_GATEWAY_ID/consumers/$CONSUMER_ID/credentials" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json"\
     -H "Accept: application/json, application/problem+json" \
     --json '{
       "display_name": "Mobile App Key 1",
       "name": "mobile-app-key-1",
       "type": "api-key"
     }'

Copied!

The response includes the generated api_key value. Store this securely; it cannot be retrieved later.

Schema

FAQs

How is an AI Consumer different from a Kong Gateway Consumer?

The runtime entity is a regular Kong Consumer. The AI Gateway surface uses the AI Gateway entity convention (display_name, name, labels), requires an authentication type field, accepts inline AI Consumer Group assignment, and lets you reference AI Policies.

How do I add credentials to an AI Consumer?

For type: api-key AI Consumers, credentials are managed through a separate credentials endpoint, not as a field on the Consumer. Create them via POST to /consumers/{id}/credentials. type: oauth AI Consumers don’t use this endpoint. See the next question.

What’s the difference between type: api-key and type: oauth?

The type declares how the AI Consumer authenticates. An api-key AI Consumer holds one or more api-key Credentials created through the credentials endpoint. An oauth AI Consumer has no Credentials. Instead, its own custom_id field is set (at creation or update time) to the identifier your OIDC provider issues (for example, a sub claim), and an authentication policy maps the incoming token to that AI Consumer.

Can an AI Consumer belong to multiple AI Consumer Groups?

Yes. An AI Consumer can be added to multiple AI Consumer Groups through the AI Consumer Group entity. See the AI Consumer Group entity reference.

How do I attach AI Policies to an AI Consumer?

Add the Policy’s name or id to the AI Consumer’s policies array. See the AI Policy entity reference.

AI Consumers

What is an AI Consumer?

Use cases for AI Consumers

Manage AI Consumers

Authentication type

AI Consumer Group membership

Attach Policies

Set up an AI Consumer

Create Consumer Credentials

Schema

FAQs

Help us make these docs great!

Still need help?