AI Auth Strategies

Your AI Models, AI Agents, and AI MCP Servers 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
• 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. 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 before forwarding MCP traffic.

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

 
flowchart LR
    Client["AI Consumer"]
    KeyAuth["Key Auth"]
    OIDC["OpenID Connect"]
    Decision{Auth?}
    AnonErr["Request Terminating w/ 401"]
    Select["AI Model, AI Agent, or
AI MCP Server selection"]
    ACLs["ACLs"]
    Allowed["AI Model A, AI Agent A,
AI MCP Server A"]
    Denied["AI Model B, AI Agent B,
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
  

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 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.

AI Auth Strategies can be created and managed through:

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

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

When you attach an AI Auth Strategy to an AI Model, AI Agent, or AI MCP Server, AI Gateway auto-provisions a shared anonymous AI Consumer with a Request Termination policy under the hood, and points the auth strategy’s failure path at it. By default, this means that any request that fails authentication (for example, no credential, an invalid token, or a valid token that doesn’t map to a known AI Consumer or Kong Identity principal) is routed to that anonymous AI Consumer and rejected with 401 Unauthorized before it reaches the AI Model, AI Agent, or AI MCP Server.

Two settings opt specific requests out of that default termination, without disabling it entirely:

• config.consumer_optional: true (openid-connect only): A valid token that doesn’t map to any AI Consumer proceeds instead of terminating. The request still carries no AI Consumer identity.
• config.principals.error_on_miss: false (key-auth and openid-connect): A request that doesn’t match any Kong Identity principal proceeds instead of terminating.

Neither setting affects a request without credentials or an invalid token, those always terminate through the anonymous AI Consumer regardless of consumer_optional or principals.error_on_miss.

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

An AI Model can use both at once, since each caller population often needs a different credential. For example, attach key-auth for internal automation that you issue static keys to, and openid-connect for user-facing applications that already authenticate through your enterprise IdP. A request from either population is authenticated if it satisfies either strategy.

AI Agents and AI MCP Servers currently accept only one AI Auth Strategy reference each.

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 falls through to the default termination behavior.

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.

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 falls through to the default termination behavior.

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 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). By default, a valid token that doesn’t match any AI Consumer falls through to the default termination behavior. Set config.consumer_optional: true to let that request proceed instead without an AI Consumer identity attached.

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.

An AI Auth Strategy can map a verified credential to an identity in two ways, and you can use either or both together.

AI Consumer mapping

AI Consumer mapping maps a credential to an AI Consumer, a AI Gateway-local identity. For key-auth, this mapping is intrinsic: the matched API key already belongs to a specific AI Consumer, created through the credentials endpoint. For openid-connect, set config.consumer_by/config.consumer_claims to map a token claim to an AI Consumer instead. By mapping to an AI Consumer, you can also use AI Consumer Group membership, access.acls, attached AI Policies, and per-consumer usage attribution.

Principal mapping

Kong Identity Principal mapping (config.principals) instead looks the credential up against a Kong Identity Principal, an identity shared across Kong Gateway, Event Gateway, and Dev Portal. A Principal carries metadata you can use in conditional plugin execution, and scales past AI Consumer limits since Principals load on demand rather than living in data plane memory. Both auth strategy types support config.principals.

You can configure both AI Consumer and Principal on the same openid-connect auth strategy. config.principals.match_consumer (enabled by default when Principals are enabled) loads the AI Consumer linked to the matched Principal, overriding whatever config.consumer_by would otherwise have resolved. This lets you manage identity centrally in Kong Identity, by linking a Principal to an AI Consumer through a control_plane_consumer identity, while still getting AI Gateway-native AI Consumer features (AI Policies, access.acls, AI Consumer Groups) for that same caller.

An AI Auth Strategy takes effect only when assigned to an AI Model, AI Agent, or 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:

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.

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:

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
      }
    }
    '

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

OIDC bearer token authentication

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

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"
      }
    }
    '

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