---
title: AI Vaults
description: AI Vaults for storing and referencing secrets used by AI Gateway
  entities.
url: "/ai-gateway/entities/ai-vault/"
canonical_url: "/ai-gateway/entities/ai-vault/"
content_type: reference
min_version:
  ai-gateway: '2.0'
products:
- AI Gateway
tools:
- Konnect API
- kongctl
canonical: true
works_on:
- konnect


---

# AI Vaults










## What is an AI Vault?

You must store secrets like API keys and authentication tokens somewhere secure instead of embedding them directly in your configurations. An AI Vault entity lets you register an external secret backend (AWS Secrets Manager, HashiCorp Vault, environment variables, or others) so that [AI Model Providers](/ai-gateway/entities/ai-model-provider/), [AI Auth Strategies](/ai-gateway/entities/ai-auth-strategy/), [AI Models](/ai-gateway/entities/ai-model/), [AI Agents](/ai-gateway/entities/ai-agent/), and [AI MCP Servers](/ai-gateway/entities/ai-mcp-server/) can reference secrets instead of storing them as literal values.

An AI Vault entity stores the connection configuration and credentials needed to reach your secret backend. When other entities reference a secret, AI Gateway:
1. Looks up the vault at request time
1. Retrieves the actual secret value
1. Uses it for authentication or configuration.

## Manage AI Vaults

AI Vaults can be created and managed through:

* Konnect UI
* [AI Gateway API](/api/konnect/ai-gateway/): `/ai-gateways/{aiGatewayId}/vaults`
* [kongctl](/kongctl/)

For configuration examples and step-by-step setup instructions, see [Set up an AI Vault](#set-up-an-ai-vault).

## Backends

Each AI Vault selects one of the supported secret backends:

* [Konnect Config Store](#konnect-config-store)
* Environment variables
* [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)
* [Google Secret Manager](https://cloud.google.com/secret-manager)
* [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault)
* [CyberArk Conjur](https://www.conjur.org/)
* [HashiCorp Vault](https://www.vaultproject.io/)

The connection details vary per backend; the Konnect UI surfaces the relevant fields based on the backend you choose.

## Which fields support AI Vault references?

AI Vault references can be used in sensitive fields across your AI Gateway entities:

### AI Model Provider
Sensitive fields: Authentication credentials (API keys, bearer tokens) in auth headers for upstream LLM providers

### AI Auth Strategy
Sensitive fields: OIDC client secret for openid-connect type providers

### AI Model
Sensitive fields: Backend-specific authentication required by target model configurations

### AI Agent
Sensitive fields: AWS IAM (SigV4) credentials for authenticating to the upstream agent when `config.upstream.auth` is set

### AI MCP Server
Sensitive fields: Encryption keys used for client session management, and AWS IAM (SigV4) credentials for authenticating to the upstream server in `upstream-server` mode




> Any field marked as supporting vault references can accept a secret reference instead of a literal value.

## How do I reference secrets?

To reference a secret stored in a vault, use the syntax:

```
{vault://vault-name/secret-key}
```

Where:
- `vault-name` is the `name` field of the vault you created
- `secret-key` is the identifier of the secret within that vault (exact format depends on the backend)

For example, if you created a vault named `prod-aws-vault` and stored an OpenAI API key under the key `openai-api-key`, reference it as:

```
{vault://prod-aws-vault/openai-api-key}
```

Here's how you'd use that reference in an AI Model Provider entity:





### Konnect API

  


```bash
curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/model-providers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "OpenAI Production",
      "name": "openai-prod",
      "type": "openai",
      "config": {
        "auth": {
          "type": "basic",
          "headers": [
            {
              "name": "Authorization",
              "value": "{vault://prod-aws-vault/openai-api-key}"
            }
          ]
        }
      }
    }
    '
```





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_model_providers:
  - ref: openai-prod
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: OpenAI Production
    name: openai-prod
    type: openai
    config:
      auth:
        type: basic
        headers:
        - name: Authorization
          value: "{vault://prod-aws-vault/openai-api-key}"
```
{: data-file="model-provider.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 Model Provider. 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 **Providers**.
1. Click **New Provider**.
1. Enter a **Display Name** (for example: `OpenAI Production`) and **Name** (for example: `openai-prod`).
1. Select a provider (for example: `openai`).
1. Configure authentication and connection settings for the selected provider type.
1. Click **Create**.










> The entire field value must be the vault reference string. You cannot use partial references like `Bearer {vault://...}`. The field itself must be exactly `{vault://vault-name/secret-key}`.

At request time, AI Gateway resolves the reference by looking up the vault name, retrieving the secret value, and using it for authentication or configuration.

## Choosing a backend for your AI Vault

Pick a backend matching your infrastructure and secret management strategy. Cloud-native deployments can use their platform's secret service (`aws`, `gcp`, `azure`), enterprises can use dedicated secret management systems (`conjur`, `hcv`), and smaller deployments can use `env` (environment variables) or `konnect` (built-in Config Store).


### `konnect`
When to use: Getting started, no external dependencies. Built-in Konnect Config Store for teams without existing secret infrastructure.

### `env`
When to use: Development, edge deployments, or environments where you control data plane startup. Secrets loaded at startup, no network calls.

### `aws`
When to use: AWS-deployed data planes. Integrate with AWS Secrets Manager or Parameter Store.

### `gcp`
When to use: GCP-deployed data planes. Integrate with Google Secret Manager.

### `azure`
When to use: Azure-deployed data planes. Integrate with Azure Key Vault.

### `conjur`
When to use: Enterprises standardized on CyberArk Conjur for centralized secrets management.

### `hcv`
When to use: Dedicated secret management with fine-grained access control. Supports token, AppRole, JWT, Kubernetes, AWS IAM, GCP, and Azure authentication.




## Caching and availability

Cloud-backed vault types (`aws`, `gcp`, `azure`, `conjur`, `hcv`) cache resolved secrets so AI Gateway doesn't hit the backend on every request. This reduces latency and vault load. The `env` backend doesn't cache because environment-variable lookups are local.

If your vault becomes unreachable, AI Gateway can continue using recently-cached secrets for a grace period, keeping your system operational during brief vault outages. This allows you to maintain service continuity even when secret infrastructure is temporarily unavailable.

Cache duration and grace periods are tunable per vault, allowing you to balance between fresh secrets (shorter cache times) and reduced vault requests (longer cache times). The default settings work for most deployments; adjust only if your secret rotation strategy or vault reliability requires custom behavior.

## Konnect Config Store

Unlike the other backends, the `konnect` type doesn't connect out to an external secret manager.
It stores secrets directly in Konnect, in a Config Store: a named container of key-value secrets that you create and populate through its own API, separate from the AI Vault entity itself.

A `konnect`-type AI Vault doesn't hold any secret values. It only references a Config Store by ID through `config.config_store_id`. The Config Store holds the actual secrets.


> Secret values are write-only. Once stored, AI Gateway never returns the value again, only the secret's `key` and timestamps.

### Manage Config Stores

Config Stores are managed through the AI Gateway API:

* Config Store: [`/ai-gateways/{aiGatewayId}/config-stores`](/api/konnect/ai-gateway/#/operations/create-ai-gateway-config-store)
* Config Store secrets: [`/ai-gateways/{aiGatewayId}/config-stores/{configStoreIdOrName}/secrets`](/api/konnect/ai-gateway/#/operations/create-ai-gateway-config-store-secret)

Both support full create, list, get, update, and delete operations.
Deleting a Config Store that still has secrets fails unless you pass `?force=true`, which cascades the delete to all secrets in that Config Store.

### Create a Config Store and add a secret

The following example creates a Config Store:



```bash
curl -X POST "https://us.api.konghq.com/v1/ai-gateways/$AI_GATEWAY_ID/config-stores" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json"\
     -H "Accept: application/json, application/problem+json" \
     --json '{
       "name": "prod-secrets"
     }'
```






Add a secret to the Config Store:

```bash
curl -X POST "https://us.api.konghq.com/v1/ai-gateways/$AI_GATEWAY_ID/config-stores/$CONFIG_STORE_ID/secrets" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json"\
     -H "Accept: application/json, application/problem+json" \
     --json '{
       "key": "openai-api-key",
       "value": "sk-my-openai-key"
     }'
```







### Reference the Config Store from a konnect-type AI Vault

Create a `konnect`-type AI Vault that points at the Config Store's `id`:





#### Konnect API

  
To create a Vault entity, call the Konnect [AI Gateway API's `/vaults` endpoint](/api/konnect/ai-gateway/#/operations/create-ai-gateway-vault). 


```bash
curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/vaults \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "prod-config-store-vault",
      "description": "Vault backed by the built-in Konnect Config Store.",
      "type": "konnect",
      "config": {
        "config_store_id": "'$CONFIG_STORE_ID'"
      }
    }
    '
```





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_vaults:
  - ref: prod-config-store-vault
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    name: prod-config-store-vault
    description: Vault backed by the built-in Konnect Config Store.
    type: konnect
    config:
      config_store_id: !secret {source: !env CONFIG_STORE_ID}
```
{: data-file="vault.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 Vault. 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 **Vaults**.
1. Click **New vault**.
1. Enter a **Display name** (for example: ``) and optional **Description** (for example: `Vault backed by the built-in Konnect Config Store.`).
1. Select a **Type** (for example: `konnect`). The available types are Konnect Config Store, Environment variables, AWS Secrets Manager, Google Secret Manager, Azure Key Vault, CyberArk Conjur, and HashiCorp Vault. The UI surfaces different configuration fields depending on the type you select.
1. If you selected **Environment variables**, enter a **Prefix** (for example: ``) to scope which environment variables this vault resolves against.
1. Click **Create**.









Reference the secret the same way as any other AI Vault:

```
{vault://prod-config-store-vault/openai-api-key}
```

## Set up an AI Vault

The following example registers an environment-variable AI Vault that resolves references against process environment variables prefixed with `KONG_`.


> AI Vault doesn't accept a `display_name` field. Only `name` and `description` identify a vault. If you include `display_name` when creating an AI Vault, AI Gateway silently ignores it.





### Konnect API

  
To create a Vault entity, call the Konnect [AI Gateway API's `/vaults` endpoint](/api/konnect/ai-gateway/#/operations/create-ai-gateway-vault). 


```bash
curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/vaults \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "prod-env-vault",
      "description": "Vault for production secrets sourced from environment variables.",
      "type": "env",
      "config": {
        "prefix": "KONG_"
      }
    }
    '
```





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_vaults:
  - ref: prod-env-vault
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    name: prod-env-vault
    description: Vault for production secrets sourced from environment variables.
    type: env
    config:
      prefix: KONG_
```
{: data-file="vault.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 Vault. 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 **Vaults**.
1. Click **New vault**.
1. Enter a **Display name** (for example: ``) and optional **Description** (for example: `Vault for production secrets sourced from environment variables.`).
1. Select a **Type** (for example: `env`). The available types are Konnect Config Store, Environment variables, AWS Secrets Manager, Google Secret Manager, Azure Key Vault, CyberArk Conjur, and HashiCorp Vault. The UI surfaces different configuration fields depending on the type you select.
1. If you selected **Environment variables**, enter a **Prefix** (for example: `KONG_`) to scope which environment variables this vault resolves against.
1. Click **Create**.









## Schema

```json
{
  "description": "Configuration for an AI Gateway Vault.",
  "type": "object",
  "properties": {
    "id": {
      "$ref": "#/components/schemas/UUID"
    },
    "created_at": {
      "$ref": "#/components/schemas/CreatedAt"
    },
    "updated_at": {
      "$ref": "#/components/schemas/UpdatedAt"
    }
  },
  "discriminator": {
    "propertyName": "type",
    "mapping": {
      "konnect": "#/components/schemas/KonnectConfigStoreVault",
      "env": "#/components/schemas/EnvironmentVariableVault",
      "aws": "#/components/schemas/AwsSecretsManagerVault",
      "gcp": "#/components/schemas/GoogleSecretManagerVault",
      "azure": "#/components/schemas/AzureKeyVault",
      "conjur": "#/components/schemas/ConjurVault",
      "hcv": "#/components/schemas/HashiCorpVault"
    }
  },
  "oneOf": [
    {
      "$ref": "#/components/schemas/KonnectConfigStoreVault"
    },
    {
      "$ref": "#/components/schemas/EnvironmentVariableVault"
    },
    {
      "$ref": "#/components/schemas/AwsSecretsManagerVault"
    },
    {
      "$ref": "#/components/schemas/GoogleSecretManagerVault"
    },
    {
      "$ref": "#/components/schemas/AzureKeyVault"
    },
    {
      "$ref": "#/components/schemas/ConjurVault"
    },
    {
      "$ref": "#/components/schemas/HashiCorpVault"
    }
  ],
  "required": [
    "id",
    "created_at",
    "updated_at"
  ]
}
```



## FAQs

- How is an AI Gateway AI Vault different from a Kong Gateway Vault?
  The runtime entity is the same secret-management abstraction. The AI Gateway surface
  manages AI Vaults through the AI entity convention (`name`, `description`,
  `labels`) and exposes them through the Konnect API alongside the other AI entities.
  Unlike other AI Gateway entities, AI Vaults don't have a `display_name` field.

- Which secret backends are supported?
  The `type` field selects the backend: `konnect`, `env`, `aws`, `gcp`, `azure`, `conjur`, or `hcv`.
  Each type carries its own `config` shape. HashiCorp Vault (`hcv`) further selects an
  `auth_method` from `token`, `cert`, `jwt`, `approle`, `kubernetes`, `gcp_iam`, `gcp_gce`,
  `aws_ec2`, `aws_iam`, or `azure`.

- How are AI Vault secrets referenced from other AI Gateway entities?
  Sensitive fields on AI Model Provider, AI Auth Strategy, AI Model, AI MCP Server, and other entities are annotated as
  referenceable. Set those fields to a vault reference string (for example, a `{vault://...}`
  placeholder) instead of a literal value. The AI Vault `name` is the lookup key.

- What does `name` control?
  `name` is a user-defined unique identifier and the stable handle used to look up the AI Vault
  configuration when other entities reference secrets. Renaming an AI Vault breaks any reference
  pointing at the old value.

- How do I add secrets to a `konnect`-type AI Vault?
  A `konnect`-type AI Vault doesn't hold secret values itself. It references a Config Store by
  [`config.config_store_id`](#konnect-config-store), and you create and manage the actual
  secrets through the Config Store's own API. For more information, see [Konnect Config Store](#konnect-config-store).


## Related Resources

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

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

- [AI Auth Strategy](/ai-gateway/entities/ai-auth-strategy/)

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

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

- [AI Consumer Credential](/ai-gateway/entities/ai-consumer/#create-consumer-credentials)