Vaults

Uses: Kong Gateway Admin API decK KIC Konnect API Terraform

What is a Vault?

Vaults allow you to securely store and then reference secrets from within other entities. This ensures that secrets aren’t visible in plaintext throughout the platform, in places such as kong.conf, declarative configuration files, logs, or the UI.

For example, you could store a certificate and a key in a Vault, then reference them from a Certificate entity. This way, the certificate and key are not stored in the entity directly and are more secure.

How do I add secrets to a Vault?

You can add secrets to Vaults in one of the following ways:

Environment variables
Konnect Config Store
Supported third-party backend vault

What can be stored as a secret?

You can store and reference the following as secrets in a Vault:

All kong.conf values¹. For example:
- Data store usernames and passwords, used with PostgreSQL and Redis
- Private X.509 certificates
Certificates and keys stored in the Certificate Kong Gateway entity
Kong Gateway license²
Referenceable plugin fields, such as third-party API keys (see table below for all values)

Konnect Config Store limitations:

¹: You can’t reference secrets stored in a Konnect Config Store Vault in kong.conf because Konnect resolves the secret after Kong Gateway connects to the Control Plane. For this same reason, you can’t use Konnect Config Store secrets directly in Lua code via the Kong PDK, for example.

²: In Konnect, the Kong Gateway license is managed and stored by Konnect, and doesn’t need to be stored manually in any Vault.

Referenceable plugin fields

The following plugin fields can be stored and referenced as secrets:

Plugin	Referenceable Plugin Fields
ACME	`config.account_email` `config.eab_hmac_key` `config.eab_kid` `config.storage_config.consul.token` `config.storage_config.redis.password` `config.storage_config.redis.username` `config.storage_config.vault.token`
AI Azure Content Safety	`config.content_safety_key` `config.content_safety_url`
AI Proxy	`config.auth.aws_access_key_id` `config.auth.aws_secret_access_key` `config.auth.azure_client_id` `config.auth.azure_client_secret` `config.auth.azure_tenant_id` `config.auth.gcp_service_account_json` `config.auth.header_name` `config.auth.header_value` `config.auth.param_name` `config.auth.param_value`
AI Proxy Advanced	`config.embeddings.auth.aws_access_key_id` `config.embeddings.auth.aws_secret_access_key` `config.embeddings.auth.azure_client_id` `config.embeddings.auth.azure_client_secret` `config.embeddings.auth.azure_tenant_id` `config.embeddings.auth.gcp_service_account_json` `config.embeddings.auth.header_name` `config.embeddings.auth.header_value` `config.embeddings.auth.param_name` `config.embeddings.auth.param_value` `config.targets.auth.aws_access_key_id` `config.targets.auth.aws_secret_access_key` `config.targets.auth.azure_client_id` `config.targets.auth.azure_client_secret` `config.targets.auth.azure_tenant_id` `config.targets.auth.gcp_service_account_json` `config.targets.auth.header_name` `config.targets.auth.header_value` `config.targets.auth.param_name` `config.targets.auth.param_value` `config.vectordb.pgvector.password` `config.vectordb.pgvector.user` `config.vectordb.redis.password` `config.vectordb.redis.sentinel_password` `config.vectordb.redis.sentinel_username` `config.vectordb.redis.username`
AI RAG Injector	`config.embeddings.auth.aws_access_key_id` `config.embeddings.auth.aws_secret_access_key` `config.embeddings.auth.azure_client_id` `config.embeddings.auth.azure_client_secret` `config.embeddings.auth.azure_tenant_id` `config.embeddings.auth.gcp_service_account_json` `config.embeddings.auth.header_name` `config.embeddings.auth.header_value` `config.embeddings.auth.param_name` `config.embeddings.auth.param_value` `config.vectordb.pgvector.password` `config.vectordb.pgvector.user` `config.vectordb.redis.password` `config.vectordb.redis.sentinel_password` `config.vectordb.redis.sentinel_username` `config.vectordb.redis.username`
AI Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
AI Request Transformer	`config.llm.auth.aws_access_key_id` `config.llm.auth.aws_secret_access_key` `config.llm.auth.azure_client_id` `config.llm.auth.azure_client_secret` `config.llm.auth.azure_tenant_id` `config.llm.auth.gcp_service_account_json` `config.llm.auth.header_name` `config.llm.auth.header_value` `config.llm.auth.param_name` `config.llm.auth.param_value`
AI Response Transformer	`config.llm.auth.aws_access_key_id` `config.llm.auth.aws_secret_access_key` `config.llm.auth.azure_client_id` `config.llm.auth.azure_client_secret` `config.llm.auth.azure_tenant_id` `config.llm.auth.gcp_service_account_json` `config.llm.auth.header_name` `config.llm.auth.header_value` `config.llm.auth.param_name` `config.llm.auth.param_value`
AI Semantic Cache	`config.embeddings.auth.aws_access_key_id` `config.embeddings.auth.aws_secret_access_key` `config.embeddings.auth.azure_client_id` `config.embeddings.auth.azure_client_secret` `config.embeddings.auth.azure_tenant_id` `config.embeddings.auth.gcp_service_account_json` `config.embeddings.auth.header_name` `config.embeddings.auth.header_value` `config.embeddings.auth.param_name` `config.embeddings.auth.param_value` `config.vectordb.pgvector.password` `config.vectordb.pgvector.user` `config.vectordb.redis.password` `config.vectordb.redis.sentinel_password` `config.vectordb.redis.sentinel_username` `config.vectordb.redis.username`
AI Semantic Prompt Guard	`config.embeddings.auth.aws_access_key_id` `config.embeddings.auth.aws_secret_access_key` `config.embeddings.auth.azure_client_id` `config.embeddings.auth.azure_client_secret` `config.embeddings.auth.azure_tenant_id` `config.embeddings.auth.gcp_service_account_json` `config.embeddings.auth.header_name` `config.embeddings.auth.header_value` `config.embeddings.auth.param_name` `config.embeddings.auth.param_value` `config.vectordb.pgvector.password` `config.vectordb.pgvector.user` `config.vectordb.redis.password` `config.vectordb.redis.sentinel_password` `config.vectordb.redis.sentinel_username` `config.vectordb.redis.username`
AWS Lambda	`config.aws_assume_role_arn` `config.aws_key` `config.aws_secret`
Azure Functions	`config.apikey` `config.clientid`
Confluent	`config.cluster_api_key` `config.cluster_api_secret` `config.confluent_cloud_api_key` `config.confluent_cloud_api_secret`
Confluent Consume	`config.cluster_api_key` `config.cluster_api_secret` `config.confluent_cloud_api_key` `config.confluent_cloud_api_secret`
Datadog	`config.host`
Forward Proxy Advanced	`config.auth_password` `config.auth_username`
GraphQL Proxy Caching Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
GraphQL Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
HTTP Log	`config.headers` `config.http_endpoint`
JWT Signer	`config.access_token_jwks_uri_client_password` `config.access_token_jwks_uri_client_username` `config.access_token_keyset_client_password` `config.access_token_keyset_client_username` `config.channel_token_jwks_uri_client_password` `config.channel_token_jwks_uri_client_username` `config.channel_token_keyset_client_password` `config.channel_token_keyset_client_username`
Kafka Consume	`config.authentication.password` `config.authentication.user`
Kafka Log	`config.authentication.password` `config.authentication.user`
Kafka Upstream	`config.authentication.password` `config.authentication.user`
LDAP Authentication Advanced	`config.bind_dn` `config.ldap_password`
Loggly	`config.key`
OAuth 2.0 Introspection	`config.authorization_value`
OpenID Connect	`config.client_id` `config.client_jwk.d` `config.client_jwk.dp` `config.client_jwk.dq` `config.client_jwk.k` `config.client_jwk.oth` `config.client_jwk.p` `config.client_jwk.q` `config.client_jwk.qi` `config.client_jwk.r` `config.client_jwk.t` `config.client_secret` `config.cluster_cache_redis.password` `config.cluster_cache_redis.sentinel_password` `config.cluster_cache_redis.sentinel_username` `config.cluster_cache_redis.username` `config.http_proxy_authorization` `config.https_proxy_authorization` `config.introspection_headers_values` `config.login_redirect_uri` `config.logout_redirect_uri` `config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username` `config.scopes` `config.session_secret`
OpenTelemetry	`config.headers` `config.logs_endpoint` `config.traces_endpoint`
Proxy Caching Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Rate Limiting	`config.redis.password` `config.redis.username`
Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Request Callout	`config.cache.redis.password` `config.cache.redis.sentinel_password` `config.cache.redis.sentinel_username` `config.cache.redis.username` `config.callouts.request.http_opts.proxy.auth_password` `config.callouts.request.http_opts.proxy.auth_username`
Request Transformer Advanced	`config.add.body` `config.add.headers` `config.add.querystring` `config.append.body` `config.append.headers` `config.append.querystring` `config.rename.body` `config.rename.headers` `config.rename.querystring` `config.replace.body` `config.replace.headers` `config.replace.querystring`
Response Rate Limiting	`config.redis.password` `config.redis.username`
SAML	`config.idp_certificate` `config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username` `config.request_signing_certificate` `config.request_signing_key` `config.response_encryption_key` `config.session_secret`
Service Protection	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Session	`config.secret`
Standard Webhooks	`config.secret_v1`
Upstream OAuth	`config.cache.redis.password` `config.cache.redis.sentinel_password` `config.cache.redis.sentinel_username` `config.cache.redis.username` `config.oauth.client_id` `config.oauth.client_secret` `config.oauth.password` `config.oauth.token_headers` `config.oauth.token_post_args` `config.oauth.username`

Plugin	Referenceable Plugin Fields
ACME	`config.account_email` `config.eab_hmac_key` `config.eab_kid` `config.storage_config.consul.token` `config.storage_config.redis.password` `config.storage_config.redis.username` `config.storage_config.vault.token`
AI Azure Content Safety	`config.content_safety_key` `config.content_safety_url`
AI Proxy	`config.auth.aws_access_key_id` `config.auth.aws_secret_access_key` `config.auth.azure_client_id` `config.auth.azure_client_secret` `config.auth.azure_tenant_id` `config.auth.gcp_service_account_json` `config.auth.header_name` `config.auth.header_value` `config.auth.param_name` `config.auth.param_value`
AI Proxy Advanced	`config.embeddings.auth.aws_access_key_id` `config.embeddings.auth.aws_secret_access_key` `config.embeddings.auth.azure_client_id` `config.embeddings.auth.azure_client_secret` `config.embeddings.auth.azure_tenant_id` `config.embeddings.auth.gcp_service_account_json` `config.embeddings.auth.header_name` `config.embeddings.auth.header_value` `config.embeddings.auth.param_name` `config.embeddings.auth.param_value` `config.targets.auth.aws_access_key_id` `config.targets.auth.aws_secret_access_key` `config.targets.auth.azure_client_id` `config.targets.auth.azure_client_secret` `config.targets.auth.azure_tenant_id` `config.targets.auth.gcp_service_account_json` `config.targets.auth.header_name` `config.targets.auth.header_value` `config.targets.auth.param_name` `config.targets.auth.param_value` `config.vectordb.redis.password` `config.vectordb.redis.sentinel_password` `config.vectordb.redis.sentinel_username` `config.vectordb.redis.username`
AI Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
AI Request Transformer	`config.llm.auth.aws_access_key_id` `config.llm.auth.aws_secret_access_key` `config.llm.auth.azure_client_id` `config.llm.auth.azure_client_secret` `config.llm.auth.azure_tenant_id` `config.llm.auth.gcp_service_account_json` `config.llm.auth.header_name` `config.llm.auth.header_value` `config.llm.auth.param_name` `config.llm.auth.param_value`
AI Response Transformer	`config.llm.auth.aws_access_key_id` `config.llm.auth.aws_secret_access_key` `config.llm.auth.azure_client_id` `config.llm.auth.azure_client_secret` `config.llm.auth.azure_tenant_id` `config.llm.auth.gcp_service_account_json` `config.llm.auth.header_name` `config.llm.auth.header_value` `config.llm.auth.param_name` `config.llm.auth.param_value`
AI Semantic Cache	`config.embeddings.auth.aws_access_key_id` `config.embeddings.auth.aws_secret_access_key` `config.embeddings.auth.azure_client_id` `config.embeddings.auth.azure_client_secret` `config.embeddings.auth.azure_tenant_id` `config.embeddings.auth.gcp_service_account_json` `config.embeddings.auth.header_name` `config.embeddings.auth.header_value` `config.embeddings.auth.param_name` `config.embeddings.auth.param_value` `config.vectordb.redis.password` `config.vectordb.redis.sentinel_password` `config.vectordb.redis.sentinel_username` `config.vectordb.redis.username`
AI Semantic Prompt Guard	`config.embeddings.auth.aws_access_key_id` `config.embeddings.auth.aws_secret_access_key` `config.embeddings.auth.azure_client_id` `config.embeddings.auth.azure_client_secret` `config.embeddings.auth.azure_tenant_id` `config.embeddings.auth.gcp_service_account_json` `config.embeddings.auth.header_name` `config.embeddings.auth.header_value` `config.embeddings.auth.param_name` `config.embeddings.auth.param_value` `config.vectordb.redis.password` `config.vectordb.redis.sentinel_password` `config.vectordb.redis.sentinel_username` `config.vectordb.redis.username`
AWS Lambda	`config.aws_assume_role_arn` `config.aws_key` `config.aws_secret`
Azure Functions	`config.apikey` `config.clientid`
Confluent	`config.cluster_api_key` `config.cluster_api_secret` `config.confluent_cloud_api_key` `config.confluent_cloud_api_secret`
Datadog	`config.host`
Forward Proxy Advanced	`config.auth_password` `config.auth_username`
GraphQL Proxy Caching Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
GraphQL Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
HTTP Log	`config.headers` `config.http_endpoint`
JWT Signer	`config.access_token_jwks_uri_client_password` `config.access_token_jwks_uri_client_username` `config.access_token_keyset_client_password` `config.access_token_keyset_client_username` `config.channel_token_jwks_uri_client_password` `config.channel_token_jwks_uri_client_username` `config.channel_token_keyset_client_password` `config.channel_token_keyset_client_username`
Kafka Log	`config.authentication.password` `config.authentication.user`
Kafka Upstream	`config.authentication.password` `config.authentication.user`
LDAP Authentication Advanced	`config.bind_dn` `config.ldap_password`
Loggly	`config.key`
OAuth 2.0 Introspection	`config.authorization_value`
OpenID Connect	`config.client_id` `config.client_jwk.d` `config.client_jwk.dp` `config.client_jwk.dq` `config.client_jwk.k` `config.client_jwk.oth` `config.client_jwk.p` `config.client_jwk.q` `config.client_jwk.qi` `config.client_jwk.r` `config.client_jwk.t` `config.client_secret` `config.cluster_cache_redis.password` `config.cluster_cache_redis.sentinel_password` `config.cluster_cache_redis.sentinel_username` `config.cluster_cache_redis.username` `config.http_proxy_authorization` `config.https_proxy_authorization` `config.introspection_headers_values` `config.login_redirect_uri` `config.logout_redirect_uri` `config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username` `config.scopes` `config.session_secret`
OpenTelemetry	`config.headers` `config.logs_endpoint` `config.traces_endpoint`
Proxy Caching Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Rate Limiting	`config.redis.password` `config.redis.username`
Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Request Transformer Advanced	`config.add.body` `config.add.headers` `config.add.querystring` `config.append.body` `config.append.headers` `config.append.querystring` `config.rename.body` `config.rename.headers` `config.rename.querystring` `config.replace.body` `config.replace.headers` `config.replace.querystring`
Response Rate Limiting	`config.redis.password` `config.redis.username`
SAML	`config.idp_certificate` `config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username` `config.request_signing_certificate` `config.request_signing_key` `config.response_encryption_key` `config.session_secret`
Service Protection	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Session	`config.secret`
Standard Webhooks	`config.secret_v1`
Upstream OAuth	`config.cache.redis.password` `config.cache.redis.sentinel_password` `config.cache.redis.sentinel_username` `config.cache.redis.username` `config.oauth.client_id` `config.oauth.client_secret` `config.oauth.password` `config.oauth.token_headers` `config.oauth.token_post_args` `config.oauth.username`

Plugin	Referenceable Plugin Fields
ACME	`config.account_email` `config.eab_hmac_key` `config.eab_kid` `config.storage_config.consul.token` `config.storage_config.redis.password` `config.storage_config.redis.username` `config.storage_config.vault.token`
AI Azure Content Safety	`config.content_safety_key` `config.content_safety_url`
AI Proxy	`config.auth.aws_access_key_id` `config.auth.aws_secret_access_key` `config.auth.azure_client_id` `config.auth.azure_client_secret` `config.auth.azure_tenant_id` `config.auth.gcp_service_account_json` `config.auth.header_name` `config.auth.header_value` `config.auth.param_name` `config.auth.param_value`
AI Proxy Advanced	`config.embeddings.auth.aws_access_key_id` `config.embeddings.auth.aws_secret_access_key` `config.embeddings.auth.azure_client_id` `config.embeddings.auth.azure_client_secret` `config.embeddings.auth.azure_tenant_id` `config.embeddings.auth.gcp_service_account_json` `config.embeddings.auth.header_name` `config.embeddings.auth.header_value` `config.embeddings.auth.param_name` `config.embeddings.auth.param_value` `config.targets.auth.aws_access_key_id` `config.targets.auth.aws_secret_access_key` `config.targets.auth.azure_client_id` `config.targets.auth.azure_client_secret` `config.targets.auth.azure_tenant_id` `config.targets.auth.gcp_service_account_json` `config.targets.auth.header_name` `config.targets.auth.header_value` `config.targets.auth.param_name` `config.targets.auth.param_value` `config.vectordb.redis.password` `config.vectordb.redis.sentinel_password` `config.vectordb.redis.sentinel_username` `config.vectordb.redis.username`
AI Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
AI Request Transformer	`config.llm.auth.aws_access_key_id` `config.llm.auth.aws_secret_access_key` `config.llm.auth.azure_client_id` `config.llm.auth.azure_client_secret` `config.llm.auth.azure_tenant_id` `config.llm.auth.gcp_service_account_json` `config.llm.auth.header_name` `config.llm.auth.header_value` `config.llm.auth.param_name` `config.llm.auth.param_value`
AI Response Transformer	`config.llm.auth.aws_access_key_id` `config.llm.auth.aws_secret_access_key` `config.llm.auth.azure_client_id` `config.llm.auth.azure_client_secret` `config.llm.auth.azure_tenant_id` `config.llm.auth.gcp_service_account_json` `config.llm.auth.header_name` `config.llm.auth.header_value` `config.llm.auth.param_name` `config.llm.auth.param_value`
AI Semantic Cache	`config.embeddings.auth.aws_access_key_id` `config.embeddings.auth.aws_secret_access_key` `config.embeddings.auth.azure_client_id` `config.embeddings.auth.azure_client_secret` `config.embeddings.auth.azure_tenant_id` `config.embeddings.auth.gcp_service_account_json` `config.embeddings.auth.header_name` `config.embeddings.auth.header_value` `config.embeddings.auth.param_name` `config.embeddings.auth.param_value` `config.vectordb.redis.password` `config.vectordb.redis.sentinel_password` `config.vectordb.redis.sentinel_username` `config.vectordb.redis.username`
AI Semantic Prompt Guard	`config.embeddings.auth.aws_access_key_id` `config.embeddings.auth.aws_secret_access_key` `config.embeddings.auth.azure_client_id` `config.embeddings.auth.azure_client_secret` `config.embeddings.auth.azure_tenant_id` `config.embeddings.auth.gcp_service_account_json` `config.embeddings.auth.header_name` `config.embeddings.auth.header_value` `config.embeddings.auth.param_name` `config.embeddings.auth.param_value` `config.vectordb.redis.password` `config.vectordb.redis.sentinel_password` `config.vectordb.redis.sentinel_username` `config.vectordb.redis.username`
AWS Lambda	`config.aws_assume_role_arn` `config.aws_key` `config.aws_secret`
Azure Functions	`config.apikey` `config.clientid`
Confluent	`config.cluster_api_key` `config.cluster_api_secret` `config.confluent_cloud_api_key` `config.confluent_cloud_api_secret`
Datadog	`config.host`
Forward Proxy Advanced	`config.auth_password` `config.auth_username`
GraphQL Proxy Caching Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
GraphQL Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
HTTP Log	`config.headers` `config.http_endpoint`
JWT Signer	`config.access_token_jwks_uri_client_password` `config.access_token_jwks_uri_client_username` `config.access_token_keyset_client_password` `config.access_token_keyset_client_username` `config.channel_token_jwks_uri_client_password` `config.channel_token_jwks_uri_client_username` `config.channel_token_keyset_client_password` `config.channel_token_keyset_client_username`
Kafka Log	`config.authentication.password` `config.authentication.user`
Kafka Upstream	`config.authentication.password` `config.authentication.user`
LDAP Authentication Advanced	`config.bind_dn` `config.ldap_password`
Loggly	`config.key`
OAuth 2.0 Introspection	`config.authorization_value`
OpenID Connect	`config.client_id` `config.client_jwk.d` `config.client_jwk.dp` `config.client_jwk.dq` `config.client_jwk.k` `config.client_jwk.oth` `config.client_jwk.p` `config.client_jwk.q` `config.client_jwk.qi` `config.client_jwk.r` `config.client_jwk.t` `config.client_secret` `config.cluster_cache_redis.password` `config.cluster_cache_redis.sentinel_password` `config.cluster_cache_redis.sentinel_username` `config.cluster_cache_redis.username` `config.introspection_headers_values` `config.login_redirect_uri` `config.logout_redirect_uri` `config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username` `config.scopes` `config.session_secret`
OpenTelemetry	`config.headers` `config.logs_endpoint` `config.traces_endpoint`
Proxy Caching Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Rate Limiting	`config.redis.password` `config.redis.username`
Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Request Transformer Advanced	`config.add.body` `config.add.headers` `config.add.querystring` `config.append.body` `config.append.headers` `config.append.querystring` `config.rename.body` `config.rename.headers` `config.rename.querystring` `config.replace.body` `config.replace.headers` `config.replace.querystring`
Response Rate Limiting	`config.redis.password` `config.redis.username`
SAML	`config.idp_certificate` `config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username` `config.request_signing_certificate` `config.request_signing_key` `config.response_encryption_key` `config.session_secret`
Session	`config.secret`
Standard Webhooks	`config.secret_v1`
Upstream OAuth	`config.cache.redis.password` `config.cache.redis.sentinel_password` `config.cache.redis.sentinel_username` `config.cache.redis.username` `config.oauth.client_id` `config.oauth.client_secret` `config.oauth.password` `config.oauth.token_headers` `config.oauth.token_post_args` `config.oauth.username`

Plugin	Referenceable Plugin Fields
ACME	`config.account_email` `config.eab_hmac_key` `config.eab_kid` `config.storage_config.consul.token` `config.storage_config.redis.password` `config.storage_config.redis.username` `config.storage_config.vault.token`
AI Azure Content Safety	`config.content_safety_key` `config.content_safety_url`
AI Proxy	`config.auth.azure_client_id` `config.auth.azure_client_secret` `config.auth.azure_tenant_id` `config.auth.header_name` `config.auth.header_value` `config.auth.param_name` `config.auth.param_value`
AI Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
AI Request Transformer	`config.llm.auth.azure_client_id` `config.llm.auth.azure_client_secret` `config.llm.auth.azure_tenant_id` `config.llm.auth.header_name` `config.llm.auth.header_value` `config.llm.auth.param_name` `config.llm.auth.param_value`
AI Response Transformer	`config.llm.auth.azure_client_id` `config.llm.auth.azure_client_secret` `config.llm.auth.azure_tenant_id` `config.llm.auth.header_name` `config.llm.auth.header_value` `config.llm.auth.param_name` `config.llm.auth.param_value`
AWS Lambda	`config.aws_assume_role_arn` `config.aws_key` `config.aws_secret`
Azure Functions	`config.apikey` `config.clientid`
Datadog	`config.host`
Forward Proxy Advanced	`config.auth_password` `config.auth_username`
GraphQL Proxy Caching Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
GraphQL Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
HTTP Log	`config.headers` `config.http_endpoint`
JWT Signer	`config.access_token_jwks_uri_client_password` `config.access_token_jwks_uri_client_username` `config.access_token_keyset_client_password` `config.access_token_keyset_client_username` `config.channel_token_jwks_uri_client_password` `config.channel_token_jwks_uri_client_username` `config.channel_token_keyset_client_password` `config.channel_token_keyset_client_username`
Kafka Log	`config.authentication.password` `config.authentication.user`
Kafka Upstream	`config.authentication.password` `config.authentication.user`
LDAP Authentication Advanced	`config.bind_dn` `config.ldap_password`
Loggly	`config.key`
OAuth 2.0 Introspection	`config.authorization_value`
OpenID Connect	`config.client_id` `config.client_jwk.d` `config.client_jwk.dp` `config.client_jwk.dq` `config.client_jwk.k` `config.client_jwk.oth` `config.client_jwk.p` `config.client_jwk.q` `config.client_jwk.qi` `config.client_jwk.r` `config.client_jwk.t` `config.client_secret` `config.introspection_headers_values` `config.login_redirect_uri` `config.logout_redirect_uri` `config.scopes` `config.session_redis_password` `config.session_redis_username` `config.session_secret`
OpenTelemetry	`config.endpoint` `config.headers`
Proxy Caching Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Rate Limiting	`config.redis.password` `config.redis.username`
Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Request Transformer Advanced	`config.add.body` `config.add.headers` `config.add.querystring` `config.append.body` `config.append.headers` `config.append.querystring` `config.rename.body` `config.rename.headers` `config.rename.querystring` `config.replace.body` `config.replace.headers` `config.replace.querystring`
Response Rate Limiting	`config.redis.password` `config.redis.username`
SAML	`config.idp_certificate` `config.request_signing_certificate` `config.request_signing_key` `config.response_encryption_key` `config.session_redis_password` `config.session_redis_username` `config.session_secret`
Session	`config.secret`

Plugin	Referenceable Plugin Fields
ACME	`config.account_email` `config.eab_hmac_key` `config.eab_kid` `config.storage_config.consul.token` `config.storage_config.redis.auth` `config.storage_config.vault.token`
AWS Lambda	`config.aws_assume_role_arn` `config.aws_key` `config.aws_secret`
Azure Functions	`config.apikey` `config.clientid`
Datadog	`config.host`
Forward Proxy Advanced	`config.auth_password` `config.auth_username`
GraphQL Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
HTTP Log	`config.headers` `config.http_endpoint`
Kafka Log	`config.authentication.password` `config.authentication.user`
Kafka Upstream	`config.authentication.password` `config.authentication.user`
LDAP Authentication Advanced	`config.bind_dn` `config.ldap_password`
Loggly	`config.key`
OAuth 2.0 Introspection	`config.authorization_value`
OpenID Connect	`config.client_id` `config.client_jwk.d` `config.client_jwk.dp` `config.client_jwk.dq` `config.client_jwk.k` `config.client_jwk.oth` `config.client_jwk.p` `config.client_jwk.q` `config.client_jwk.qi` `config.client_jwk.r` `config.client_jwk.t` `config.client_secret` `config.introspection_headers_values` `config.login_redirect_uri` `config.logout_redirect_uri` `config.scopes` `config.session_redis_password` `config.session_redis_username` `config.session_secret`
OpenTelemetry	`config.endpoint` `config.headers`
Proxy Caching Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Rate Limiting	`config.redis_password` `config.redis_username`
Rate Limiting Advanced	`config.redis.password` `config.redis.sentinel_password` `config.redis.sentinel_username` `config.redis.username`
Request Transformer Advanced	`config.add.body` `config.add.headers` `config.add.querystring` `config.append.body` `config.append.headers` `config.append.querystring` `config.rename.body` `config.rename.headers` `config.rename.querystring` `config.replace.body` `config.replace.headers` `config.replace.querystring`
Response Rate Limiting	`config.redis_password` `config.redis_username`
SAML	`config.idp_certificate` `config.request_signing_certificate` `config.request_signing_key` `config.response_encryption_key` `config.session_redis_password` `config.session_redis_username` `config.session_secret`
Session	`config.secret`

Supported Vault backends

Each vault has its own required configuration. You can provide this configuration by creating a Vault entity, or by configuring specific environment variables before starting Kong Gateway.

For more information, choose a Vault below to see the specific configuration required.

Backend	Kong Gateway OSS	Kong Gateway Enterprise	Konnect supported
Environment variable
Konnect Config Store
AWS Secrets Manager
Azure Key Vaults
Google Cloud Secret
HashiCorp Vault

How do I reference secrets stored in a Vault?

When you want to use a secret stored in a Vault, you can reference the secret with a vault reference. You can use the vault reference in places such as kong.conf, declarative configuration files, logs, or in the UI.

The Vault backend may store multiple related secrets inside an object, but the reference should always point to a key that resolves to a string value. For example, the following reference:

{vault://hcv/pg/username}

Would point to a secret object called pg inside a HashiCorp Vault, which may return the following value:

{
  "username": "john",
  "password": "doe"
}

Kong Gateway receives the payload and extracts the "username" value of "john" for the secret reference of {vault://hcv/pg/username}.

Vault references must be used for the whole referenced value. Imagine that you’re calling a upstream service with the authentication token ABC123:

Works	Configuration Value	Vault Value
❌	Bearer {vault://hcv/myservice-auth-token}	ABC123
✅	{vault://hcv/myservice-auth-token}	Bearer ABC123

Secret rotation in Vaults

By default, Kong Gateway automatically refreshes secrets once every minute in the background. You can also configure how often Kong Gateway refreshes secrets using the Vault entity configuration.

There are two types of refresh configuration available:

Refresh periodically using TTLs: For example, check for a new TLS certificate once per day.
Refresh on failure: For example, on a database authentication failure, check if the secrets were updated, and try again.

For more information, see Secret management.

Schema

The Vault entity can only be used once the database is initialized. Secrets for values that are used before the database is initialized can’t make use of the Vaults entity.

Vault provider-specific configuration parameters

When you set up a Vault, each provider has specific parameters that you can or must configure to integrate the Vault entity with a provider.

Parameter	Field name	Description
`vaults.config.prefix`	config-prefix (Kong Manager) Environment variable prefix (Konnect)	The prefix for the environment variable that the value will be stored in.

Parameter	Field name	Description
`vaults.config.region`	AWS region	The AWS region where your vault is located.
`vaults.config.endpoint_url` v3.4+	AWS Secrets Manager Endpoint URL	The endpoint URL of the AWS Secrets Manager service. If not specified, the default is `https://secretsmanager.{region}.amazonaws.com`. You can override this by specifying a complete URL including the `http/https` scheme.
`vaults.config.assume_role_arn` v3.4+	Assume AWS IAM role ARN	The target IAM role ARN to assume when accessing AWS Secrets Manager. If specified, the backend will assume this role using your current runtime’s IAM Role. Leave empty if not using an assumed role.
`vaults.config.role_session_name` v3.4+	Role Session Name	The session name used when assuming a role. Defaults to `KongVault`.
`vaults.config.sts_endpoint_url` v3.8+	AWS STS Endpoint URL	A custom STS endpoint URL used for IAM role assumption. Overrides the default `https://sts.amazonaws.com` or regional variant `https://sts.<region>.amazonaws.com`. Include the full `http/https` scheme. Only specify this if using a private VPC endpoint for STS.
`vaults.config.ttl`	TTL	The time-to-live (in seconds) for cached secrets. A value of 0 (default) disables rotation. If non-zero, use at least 60 seconds.
`vaults.config.neg_ttl`	Negative TTL	The TTL (in seconds) for caching failed secret lookups. A value of 0 (default) disables negative caching. When the TTL expires, Kong will retry fetching the secret.
`vaults.config.resurrect_ttl`	Resurrect TTL	The duration (in seconds) for which expired secrets will continue to be used if the vault is unreachable or the secret is deleted. After this time, Kong stops retrying. The default is 1e8 seconds (~3 years) to ensure resilience during unexpected issues.

Parameter	Field name	Description
`vaults.config.vault_uri`	Vault URI	The URI from which the vault is reachable. This value can be found in your Azure Key Vault Dashboard under the Vault URI entry.
`vaults.config.client_id`	Client ID	The client ID for your registered application. You can find this in the Azure Dashboard under App Registrations.
`vaults.config.tenant_id`	Tenant ID	The `DirectoryId` and `TenantId` are the same: both refer to the GUID representing your Azure Active Directory tenant. Microsoft documentation and products may use either term depending on context.
`vaults.config.location`	Location	Each Azure geography includes one or more regions that meet specific data residency and compliance requirements.
`vaults.config.type`	Type	Azure Key Vault supports different data types such as keys, secrets, and certificates. Kong currently supports only `secrets`.
`vaults.config.ttl`	TTL	Time-to-live (in seconds) for a cached secret. A value of 0 (default) means no rotation. For non-zero values, it is recommended to use intervals of at least 60 seconds.
`vaults.config.neg_ttl`	Negative TTL	Time-to-live (in seconds) for caching failed secret lookups. A value of 0 (default) disables negative caching. After `neg_ttl` expires, Kong retries fetching the secret.
`vaults.config.resurrect_ttl`	Resurrect TTL	Duration (in seconds) that secrets remain usable after expiration (`config.ttl` limit). Useful when the vault is unreachable or a secret is deleted. Kong retries refreshing the secret for this duration. Afterward, it stops. The default is 1e8 seconds (~3 years) to ensure resiliency during issues.

Parameter	Field name	Description
`vaults.config.project_id`	Google Project ID	The project ID from your Google API Console. You can find it by visiting your Google API Console and selecting “Manage all projects” in the projects list.
`vaults.config.ttl`	TTL	Time-to-live (in seconds) for a cached secret. A value of 0 (default) disables rotation. For non-zero values, use a minimum of 60 seconds.
`vaults.config.neg_ttl`	Negative TTL	Time-to-live (in seconds) for caching failed secret lookups. A value of 0 (default) disables negative caching. Kong will retry fetching the secret after `neg_ttl` expires.
`vaults.config.resurrect_ttl`	Resurrect TTL	Time (in seconds) that secrets remain in use after expiration (`config.ttl` ends). Useful if the vault is unreachable or the secret is deleted but not yet replaced. Kong continues to retry for `resurrect_ttl` seconds before giving up. The default is 1e8 seconds (~3 years) to support uninterrupted service during outages.

Parameter	Field name	Description
`vaults.config.protocol`	config-protocol (Kong Manager) Protocol (Konnect)	The protocol to connect with. Accepts one of `http` or `https`.
`vaults.config.host`	config-host (Kong Manager) Host (Konnect)	The hostname of your HashiCorp vault.
`vaults.config.port`	config-port (Kong Manager) Port (Konnect)	The port number of your HashiCorp vault.
`vaults.config.mount`	config-mount (Kong Manager) Mount (Konnect)	The mount point.
`vaults.config.kv`	config-kv (Kong Manager) Kv (Konnect)	The secrets engine version. Accepts `v1` or `v2`.
`vaults.config.token`	config-token (Kong Manager) Token (Konnect)	A token string.
`vaults.config.ttl`	TTL	Time-to-live (in seconds) for a cached secret. A value of 0 (default) disables rotation. For non-zero values, use at least 60 seconds.
`vaults.config.neg_ttl`	Negative TTL	Time-to-live (in seconds) for caching failed secret lookups. A value of 0 (default) disables negative caching. Kong retries after `neg_ttl` expires.
`vaults.config.resurrect_ttl`	Resurrect TTL	Time (in seconds) that secrets remain in use after expiration (`config.ttl` is over). Useful if the vault is unreachable or a secret is deleted. Kong continues retrying for `resurrect_ttl` seconds, then stops. Default is 1e8 seconds (~3 years).
`vaults.config.namespace` v3.1+	namespace	Namespace for the Vault. Vault Enterprise requires a namespace to connect successfully.
`vaults.config.auth_method` v3.1+	auth-method	Defines the authentication mechanism for connecting to the HashiCorp Vault service. Accepts `token`, `kubernetes`, or `approle`.
`vaults.config.kube_role` v3.1+	kube-role	Role assigned to the Kubernetes service account. Only used when `keyring_vault_auth_method` is set to `kubernetes`.
`vaults.config.kube_api_token_file` v3.1+	kube-api-token-file	Path to the Kubernetes service account token file. Defaults to `/run/secrets/kubernetes.io/serviceaccount/token` if unspecified.
`vaults.config.kube_auth_path` v3.4+	kube-auth-path	Path for enabling the Kubernetes auth method. Defaults to `kubernetes`. Single leading/trailing slashes are trimmed.
`vaults.config.approle_auth_path` v3.4+	approle_auth_path	Path for enabling the AppRole auth method. Defaults to `AppRole`. Single leading/trailing slashes are trimmed.
`vaults.config.approle_role_id` v3.4+	approle_role_id	Specifies the AppRole role ID in HashiCorp Vault.
`vaults.config.approle_secret_id` v3.4+	approle_secret_id	Defines the AppRole’s secret ID in HashiCorp Vault.
`vaults.config.approle_secret_id_file` v3.4+	approle_secret_id_file	Path to a file containing the AppRole secret ID.
`vaults.config.approle_response_wrapping` v3.4+	approle_response_wrapping	Whether the secret ID is a response-wrapping token. Defaults to `false`. When `true`, Kong unwraps the token to get the actual secret ID. Note: tokens can only be unwrapped once; distribute them individually to Kong nodes.

Set up a Vault

_format_version: "3.0"
vaults:
  - name: env
    description: ENV vault for secrets
    prefix: my-env-vault
    config:
      prefix: MY_SECRET_

curl -i -X POST http://localhost:8001/vaults/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "env",
      "description": "ENV vault for secrets",
      "prefix": "my-env-vault",
      "config": {
        "prefix": "MY_SECRET_"
      }
    }
    '

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/vaults/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "env",
      "description": "ENV vault for secrets",
      "prefix": "my-env-vault",
      "config": {
        "prefix": "MY_SECRET_"
      }
    }
    '

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

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

echo "
apiVersion: configuration.konghq.com/v1alpha1
kind: KongVault
metadata:
  name: env-vault
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
spec:
  backend: env
  description: ENV vault for secrets
  prefix: my-env-vault
  config:
    prefix: MY_SECRET_
" | kubectl apply -f -

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

resource "konnect_gateway_vault" "my_vault" {
  description = "ENV vault for secrets"
  prefix = "my-env-vault"
  config = {
    prefix = "MY_SECRET_"
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

The following creates a new Vault with basic configuration:

In Kong Manager or Gateway Manager, navigate to a control plane and click Vaults in the sidebar.
Click New Vault.
Select a configuration for the Vault. For example: env
Enter a prefix for the Vault. For example: my-env-vault
Enter a description for the Vault. For example: ENV vault for secrets
Click Save.

Store secrets as environment variables

You can store secrets as environment variables instead of configuring a Vault entity or third-party backend vault.

Use case	Environment variable example	Secret reference example
Single secret value	`export MY_SECRET_VALUE=example-secret`	`{vault://env/my-secret-value}`
Multiple secrets (flat JSON string)	`export PG_CREDS='{"username":"user", "password":"pass"}'`	`{vault://env/pg-creds/username}` `{vault://env/pg-creds/password}`

FAQs

What types of fields can be used in Vaults?

Vaults work with “referenceable” fields. All fields in kong.conf are referenceable and some fields within entities (for example, plugins, certificates) are also. Refer to the appropriate entity documentation to learn more.

Can Vaults be referenced during custom plugin development?

Yes. The plugin development kit (PDK) offers a Vaults module (kong.vault) that can be used to resolve, parse, and verify Vault references.

What data types can I use when referencing a secret in a Vault?

A secret reference points to a string value. No other data types are currently supported.

I have a secret with multiple versions, how do I specify an earlier version when I’m referencing the secret?

If you have a secret with multiple versions, you can access the current version or any previous version of the secret by specifying a version in the reference.

In the following AWS example, AWSCURRENT refers to the latest secret version and AWSPREVIOUS refers to an older version:

# For AWSCURRENT, not specifying version
{vault://aws/secret-name/foo}

# For AWSCURRENT, specifying version == 1
{vault://aws/secret-name/foo#1}

# For AWSPREVIOUS, specifying version == 2
{vault://aws/secret-name/foo#2}

This applies to all providers with versioned secrets.

My secret in AWS Secret Manager has a / backslash in the secret name. How do I reference this secret in Kong Gateway?

The slash symbol (/) is a valid character for the secret name in AWS Secrets Manager. If you want to reference a secret name that starts with a slash or has two consecutive slashes, transform one of the slashes in the name into URL-encoded format. For example:

A secret named /secret/key should be referenced as {vault://aws/%2Fsecret/key}
A secret named secret/path//aaa/key should be referenced as {vault://aws/secret/path/%2Faaa/key}

Since Kong Gateway tries to resolve the secret reference as a valid URL, using a slash instead of a URL-encoded slash will result in unexpected secret name fetching.

I have secrets stored in multiple AWS Secret Manager regions, how do I reference those secrets in Kong Gateway?

You can create multiple Vault entities, one per region with the config.region parameter. You’d then reference the secret by the name of the Vault:

{vault://aws-eu-central-vault/secret-name/foo}
{vault://aws-us-west-vault/secret-name/snip}

I’m using Google Workload Identity, how do I configure a Vault?

To use GCP Secret Manager with Workload Identity on a GKE cluster, update your pod spec so that the service account (GCP_SERVICE_ACCOUNT) is attached to the pod. For configuration information, read the Workload Identity configuration documentation.

Notes:

With Workload Identity, setting the GCP_SERVICE_ACCOUNT isn’t necessary.

When using GCP Vault as a backend, make sure you have configured system as part of the lua_ssl_trusted_certificate configuration directive so that the SSL certificates used by the official GCP API can be trusted by Kong Gateway.

How does Kong Gateway retrieve secrets from HashiCorp Vault?

Kong Gateway retrieves secrets from HashiCorp Vault’s HTTP API through a two-step process: authentication and secret retrieval.

Step 1: Authentication

Depending on the authentication method defined in config.auth_method, Kong Gateway authenticates to HashiCorp Vault using one of the following methods:

If you’re using the token auth method, Kong Gateway uses the config.token as the client token.
If you’re using the kubernetes auth method, Kong Gateway uses the service account JWT token mounted in the pod (path defined in the config.kube_api_token_file) to call the login API for the Kubernetes auth path on the HashiCorp Vault server and retrieve a client token.
v3.4+ If you’re using the approle auth method, Kong Gateway uses the AppRole credentials to retrieve a client token. The AppRole role ID is configured by field config.approle_role_id, and the secret ID is configured by field config.approle_secret_id or config.approle_secret_id_file.
- If you set config.approle_response_wrapping to true, then the secret ID configured by config.approle_secret_id or config.approle_secret_id_file will be a response wrapping token, and Kong Gateway will call the unwrap API /v1/sys/wrapping/unwrap to unwrap the response wrapping token to fetch the real secret ID. Kong Gateway will use the AppRole role ID and secret ID to call the login API for the AppRole auth path on the HashiCorp Vault server and retrieve a client token.

By calling the login API, Kong Gateway will retrieve a client token and then use it in the next step as the value of X-Vault-Token header to retrieve a secret.

Step 2: Retrieving the secret

Kong Gateway uses the client token retrieved in the authentication step to call the Read Secret API and retrieve the secret value. The request varies depending on the secrets engine version you’re using. Kong Gateway will parse the response of the read secret API automatically and return the secret value.

Next Steps

Set up a Konnect Config Store

Set up HashiCorp Vault as a vault backend

Keyring