---
title: AI Auth Strategies
description: Configure inbound AI Consumer authentication for AI Models, AI Agents,
  and AI MCP Servers in AI Gateway.
url: "/ai-gateway/entities/ai-auth-strategy/"
canonical_url: "/ai-gateway/entities/ai-auth-strategy/"
content_type: reference
min_version:
  ai-gateway: '2.0'
products:
- AI Gateway
tools:
- Konnect API
- kongctl
canonical: true
works_on:
- konnect


---

# AI Auth Strategies










## What is an AI Auth Strategy?

Your [AI Models](/ai-gateway/entities/ai-model/), [AI Agents](/ai-gateway/entities/ai-agent/), and [AI MCP Servers](/ai-gateway/entities/ai-mcp-server/) often need access control: some teams should reach certain AI Models, AI Agents, or AI MCP Servers and others should not, and you need a way to verify who is calling before a request consumes tokens or touches sensitive data. An AI Auth Strategy lets you declare an inbound authentication mechanism at the gateway level and attach it to specific AI Models, AI Agents, or AI MCP Servers.

Use AI Auth Strategies to:
* Authenticate API keys and map them to [AI Consumers](/ai-gateway/entities/ai-consumer/)
* Authenticate enterprise users through an existing identity provider (Okta, Azure AD, Google, or any OIDC-compliant IdP) without managing keys manually
* Apply different authentication to different models, agents, or MCP servers. For example, API keys for internal automation and OIDC bearer tokens for user-facing applications.

An AI Auth Strategy manages inbound authentication, which is distinct from the outbound credentials managed by an [AI Model Provider](/ai-gateway/entities/ai-model-provider/). When an AI Consumer calls an AI Model, AI Agent, or AI MCP Server, the AI Auth Strategy checks who they are. The AI Model then uses the AI Model Provider's credentials to forward the request upstream; an AI Agent proxies the now-authenticated request directly to its upstream agent; an AI MCP Server uses the resolved identity for [ACL tool control](/ai-gateway/entities/ai-mcp-server/#acl-tool-control) before forwarding MCP traffic.

The following diagram shows where authentication fits in the request pipeline:

<pre class='mermaid'> 
flowchart LR
    Client["AI Consumer"]
    KeyAuth["Key Auth"]
    OIDC["OpenID Connect"]
    Decision{Auth?}
    AnonErr["Request Terminating w/ 401"]
    Select["AI Model, AI Agent, or<br/>AI MCP Server selection"]
    ACLs["ACLs"]
    Allowed["AI Model A, AI Agent A,<br/>AI MCP Server A"]
    Denied["AI Model B, AI Agent B,<br/>AI MCP Server B"]

    Client-->KeyAuth
    KeyAuth-->OIDC
    OIDC-->Decision
    Decision-->|no auth|AnonErr
    Decision-->|auth|Select
    Select-->|selects entity|ACLs
    ACLs-->|allowed|Allowed
    ACLs-->|denied|Denied
  </pre>

Authentication behaves like any other Kong plugin: it runs after route selection, in the context of the matched route, but before the AI Model, AI Agent, or AI MCP Server is selected. This means unauthenticated requests never reach that selection step or its policy evaluation.


> This diagram shows the general `key-auth`/`openid-connect` check. For an AI MCP Server with [`access.metadata`](/ai-gateway/entities/ai-mcp-server/#protected-resource-metadata) set, token validation instead runs through a generated AI MCP OAuth2 configuration, which adds OAuth 2.1 resource-server checks (token audience validation, protected resource metadata serving) on top of this AI Auth Strategy.

## Manage AI Auth Strategies

AI Auth Strategies can be created and managed through:

* Konnect UI
* AI Gateway API: `/v1/ai-gateways/{aiGatewayId}/auth-strategies`
* [kongctl](/kongctl/)

For configuration examples and step-by-step setup instructions, see [Set up an AI Auth Strategy](#set-up-an-ai-auth-strategy).

## Authentication types

AI Gateway supports two auth strategy types. Choose based on how your AI Consumers authenticate:

### `key-auth`
When to use: Your AI Consumers are internal tools, scripts, or teams that you control. You want to issue and rotate static API keys without involving an external identity provider.
AI Consumer credential: API key in a request header, query parameter, or request body

### `openid-connect`
When to use: Your AI Consumers already authenticate through an enterprise IdP (Okta, Azure AD, Google, or similar). You want to accept the tokens they already have rather than issuing separate keys.
AI Consumer credential: JWT bearer token or OAuth 2.0 grant from an external IdP



### API key authentication

The `key-auth` auth strategy validates an API key that the AI Consumer passes on every request. The gateway looks for the key in a configurable header or query parameter, checks it against the AI Consumer's registered key, and either authenticates the request or routes it to the anonymous AI Consumer (which terminates with `401`).

By default, AI Gateway accepts the key in an `apikey` header or `apikey` query parameter. Override the key name with `config.key_names`. For example, set `config.key_names: ["X-API-Key"]` to enforce a standard header name across your APIs.

#### `key_in_header`
Default: `true`
Description: Accept the key in a request header.

#### `key_in_query`
Default: `true`
Description: Accept the key as a query parameter.

#### `key_in_body`
Default: `false`
Description: Accept the key in the request body. Supports `application/json`, `application/x-www-form-urlencoded`, and `multipart/form-data`.

#### `hide_credentials`
Default: `true`
Description: Strip the key from the request before forwarding upstream.



### OIDC token authentication

The `openid-connect` auth strategy validates a JWT or OAuth 2.0 token that the AI Consumer obtains from an external IdP. The gateway verifies the token against the IdP's published keys, maps the token to an AI Consumer, and either authenticates the request or routes it to the anonymous AI Consumer (which terminates with `401`).

Set `config.issuer` to the IdP's discovery URL (for example, `https://dev-123456.okta.com`). AI Gateway uses the OIDC discovery endpoint to fetch signing keys automatically.

The default `config.auth_methods` are `bearer` and `client_credentials`. If your AI Consumers use a different grant flow, add it to the list. For a full list of supported values, see the [Schema](#schema) section.

To map the token to an existing AI Consumer, set `config.consumer_claims` to an array of path segments locating the claim in the token that carries the AI Consumer identifier (for example, `[["user", "info", "id"]]` to map to a nested `user.info.id` claim). If no mapping is needed, set `config.consumer_optional: true` to allow unauthenticated token holders through ACL checks.

`config.cache_tokens_salt` is required for `openid-connect` AI Auth Strategies. It's a string used to generate the cache key for token endpoint request caching; set it to any unique value for this provider instance.


> All AI Models in the same AI Gateway that use OIDC authentication must reference the same `openid-connect` AI Auth Strategy. Using different OIDC providers across models in the same AI Gateway is not supported.

## Assigning an AI Auth Strategy

An AI Auth Strategy takes effect only when assigned to an [AI Model](/ai-gateway/entities/ai-model/), [AI Agent](/ai-gateway/entities/ai-agent/), or [AI MCP Server](/ai-gateway/entities/ai-mcp-server/) (`conversion-listener`, `listener`, or `passthrough-listener` mode). Reference the provider by `name` or `id` in the entity's `access.auth_strategies` array:

```yaml
access:
  auth_strategies:
    - my-key-auth-provider
  acls:
    allow:
      - allowed-ai-consumer-group
```


> **Assignment rules**
> * Each AI Model supports one `key-auth` auth strategy and one `openid-connect` auth strategy. You can assign both types to the same AI Model; a request is authenticated if it satisfies either strategy.
> * Each AI Agent currently supports up to one AI Auth Strategy reference.
> * Each AI MCP Server (`conversion-listener`, `listener`, or `passthrough-listener` mode) currently supports up to one AI Auth Strategy reference. `upstream-server` AI MCP Servers authenticate to their upstream separately, through `config.server.tools_list_auth`; `conversion-only` AI MCP Servers have no `access` field.
> * AI Auth Strategies are the only supported way to authenticate inbound AI Consumer traffic to an AI Model, AI Agent, or AI MCP Server, and let each entity use different authentication independently. This is separate from outbound authentication to the upstream LLM, agent, or MCP server, which is configured on the AI Model Provider or the entity's own `config.upstream.auth`.

If you plan to rename the AI Auth Strategy later, reference it by `id` rather than name. The ID is stable across renames.

## Set up an AI Auth Strategy

### API key authentication

The following example creates a `key-auth` AI Auth Strategy that accepts AI Consumer API keys in the `X-API-Key` header:





#### Konnect API

  


```bash
curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/auth-strategies \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "API Key Auth",
      "name": "api-key-auth",
      "type": "key-auth",
      "config": {
        "key_names": [
          "X-API-Key"
        ],
        "key_in_header": true,
        "key_in_query": false,
        "hide_credentials": true
      }
    }
    '
```





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_auth_strategies:
  - ref: api-key-auth
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: API Key Auth
    name: api-key-auth
    type: key-auth
    config:
      key_names:
      - X-API-Key
      key_in_header: true
      key_in_query: false
      hide_credentials: true
```
{: data-file="auth-strategy.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 Auth Strategy. Suggested values are shown in backticks:

<!-- TODO: verify the "Auth Strategies" sidebar entry and "New auth strategy" button labels against the UI -->

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 **Auth Strategies**.
1. Click **New auth strategy**.
1. Enter a **Display name** (for example: `API Key Auth`) and select a **Type**, either **Key authentication** or **OpenID Connect**.
1. If you selected **Key authentication**, configure the key names and where the key is checked (header, query, or body).
1. If you selected **OpenID Connect**, enter an **Issuer**, **Client ID**, and **Client secret**, and configure the claim used to match requests to a consumer.
1. Click **Create**.

The following creates a new AI Policy. 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 **Policies**.
1. Click **New Policy**.
1. Enter a **Display Name** (for example: `API Key Auth`) and **Name** (for example: `api-key-auth`).
1. Select a policy **Type** (for example: `key-auth`).
1. Configure the policy `config` fields.
1. Click **Create**.









### OIDC bearer token authentication

The following example creates an `openid-connect` AI Auth Strategy that accepts bearer tokens issued by Okta:





#### Konnect API

  


```bash
curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/auth-strategies \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "Okta AI SE",
      "name": "okta-ai-se",
      "type": "openid-connect",
      "config": {
        "issuer": "https://dev-123456.okta.com",
        "client_id": [
          "my-client-id"
        ],
        "client_secret": [
          "my-client-secret"
        ],
        "auth_methods": [
          "bearer"
        ],
        "scopes": [
          "openid"
        ],
        "cache_tokens_salt": "okta-ai-se-cache-salt"
      }
    }
    '
```





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_auth_strategies:
  - ref: okta-ai-se
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Okta AI SE
    name: okta-ai-se
    type: openid-connect
    config:
      issuer: https://dev-123456.okta.com
      client_id:
      - my-client-id
      client_secret:
      - my-client-secret
      auth_methods:
      - bearer
      scopes:
      - openid
      cache_tokens_salt: okta-ai-se-cache-salt
```
{: data-file="auth-strategy.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 Auth Strategy. Suggested values are shown in backticks:

<!-- TODO: verify the "Auth Strategies" sidebar entry and "New auth strategy" button labels against the UI -->

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 **Auth Strategies**.
1. Click **New auth strategy**.
1. Enter a **Display name** (for example: `Okta AI SE`) and select a **Type**, either **Key authentication** or **OpenID Connect**.
1. If you selected **Key authentication**, configure the key names and where the key is checked (header, query, or body).
1. If you selected **OpenID Connect**, enter an **Issuer**, **Client ID**, and **Client secret**, and configure the claim used to match requests to a consumer.
1. Click **Create**.

The following creates a new AI Policy. 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 **Policies**.
1. Click **New Policy**.
1. Enter a **Display Name** (for example: `Okta AI SE`) and **Name** (for example: `okta-ai-se`).
1. Select a policy **Type** (for example: `openid-connect`).
1. Configure the policy `config` fields.
1. Click **Create**.









## Schema

```json
{
  "discriminator": {
    "propertyName": "type",
    "mapping": {
      "key-auth": "#/components/schemas/AIGatewayAuthStrategyKeyAuthResponse",
      "openid-connect": "#/components/schemas/AIGatewayAuthStrategyOpenIDConnectResponse"
    }
  },
  "oneOf": [
    {
      "$ref": "#/components/schemas/AIGatewayAuthStrategyKeyAuthResponse"
    },
    {
      "$ref": "#/components/schemas/AIGatewayAuthStrategyOpenIDConnectResponse"
    }
  ]
}
```



## FAQs

- What is the difference between an AI Auth Strategy and an AI Model Provider?
  An AI Auth Strategy manages inbound authentication: it validates the credentials that AI Consumers
  present when calling an AI Model. An AI Model Provider manages outbound credentials: the secrets
  AI Gateway uses to authenticate to an upstream LLM service on behalf of the AI Consumer.

- Can an AI Model use both key-auth and OIDC authentication at the same time?
  Yes. An AI Model supports one `key-auth` AI Auth Strategy and one `openid-connect`
  AI Auth Strategy simultaneously. An AI Consumer's request is authenticated
  if it satisfies either strategy. Attaching an authentication AI Policy directly to an AI
  Model's `policies` field isn't supported; AI Auth Strategies are the only supported way
  to authenticate AI Model traffic.

- Can an AI Agent use an AI Auth Strategy too?
  Yes. Reference an AI Auth Strategy by `name` or `id` in the AI Agent's `access.auth_strategies`
  array, the same field used on AI Models. An AI Agent currently accepts up to one AI Auth Strategy
  reference. Attaching an authentication AI Policy directly to an AI Agent's `policies` field isn't
  supported; AI Auth Strategies are the only supported way to authenticate AI Agent traffic.

- Can an AI MCP Server use an AI Auth Strategy too?
  Yes, for `conversion-listener`, `listener`, and `passthrough-listener` AI MCP Servers. Reference an AI
  Auth Strategy by `name` or `id` in the AI MCP Server's `access.auth_strategies` array. An AI MCP
  Server currently accepts up to one AI Auth Strategy reference. `upstream-server` AI MCP Servers
  authenticate to their upstream separately, through `config.server.tools_list_auth`, and
  `conversion-only` AI MCP Servers have no `access` field since they never accept incoming MCP traffic
  directly. As with AI Agents, attaching an authentication AI Policy directly to an AI MCP Server's
  `policies` field isn't supported.

- What happens when a request carries no valid credentials?
  AI Gateway treats the request as an anonymous AI Consumer. A request-termination
  policy on that anonymous AI Consumer returns `401 Unauthorized` before the request reaches
  the AI Model, AI Agent, or AI MCP Server.

- Can I reuse the same AI Auth Strategy across multiple AI Models, AI Agents, or AI MCP Servers?
  Yes. Create an AI Auth Strategy once and reference it by `name` or `id` in the
  `access.auth_strategies` array of any AI Model, AI Agent, or AI MCP Server in the same gateway.

- Which OIDC flows does the openid-connect type support?
  By default, bearer token and client credentials flows are enabled. The full set includes
  `authorization_code`, `bearer`, `client_credentials`, `introspection`, `kong_oauth2`,
  `password`, `refresh_token`, `session`, and `userinfo`. Configure which flows are active
  with `config.auth_methods`.


## Related Resources

- [About AI Gateway](/ai-gateway/)

- [AI Model entity](/ai-gateway/entities/ai-model/)

- [AI Model Provider entity](/ai-gateway/entities/ai-model-provider/)

- [AI Agent entity](/ai-gateway/entities/ai-agent/)

- [AI MCP Server entity](/ai-gateway/entities/ai-mcp-server/)

- [AI Consumer entity](/ai-gateway/entities/ai-consumer/)

- [AI Consumer Group entity](/ai-gateway/entities/ai-consumer-group/)

- [Set up a Kong Identity auth server for AI Agent authentication](/ai-gateway/set-up-kong-identity-for-a2a/)

- [Enforce tiered AI budgets on AI Models with Kong Identity](/ai-gateway/enforce-tiered-ai-budgets-with-kong-identity/)